diff --git a/AGENTS.md b/AGENTS.md index 01bda39..b0a7374 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,9 @@ Before working here, read the shared [Simple Analytics instructions](https://git ## Tracker changes -1. **Minimize shipped bytes.** Keep changes small and reuse existing helpers and variables. Measure minified and gzip byte differences for affected scripts against the target branch using the same build and compression settings. Test proposed optimizations: extracting repeated strings can increase gzip size. +1. **Minimize shipped bytes.** Keep changes small and reuse existing helpers and variables. Measure minified, gzip, and brotli byte differences for affected scripts against the target branch using the same build and compression settings. Test proposed optimizations: extracting repeated strings can increase gzip size. + + The tracker should balance size against edge cases, not handle every edge case. Cover the common browsers and flows; accept small data loss in rare cases, such as old browser versions, unusual event orders, or invalid settings, instead of adding code for them. When a change fixes edge cases, list each part with its minified/gzip/brotli cost and what is lost without it, so each part can be kept or dropped on purpose. 2. **Preserve existing installations.** Unless the user explicitly accepts a behavior change, preserve existing settings and integrations. Check affected combinations against the [customer documentation](https://docs.simpleanalytics.com/), including manual pageviews, query handling, attribution, namespaces, ignored metrics, metadata, and automatic events. Report concrete before/after effects on customer data, event names, and counts, separately from additions that leave existing installations unchanged. @@ -18,7 +20,7 @@ Before working here, read the shared [Simple Analytics instructions](https://git 5. **Keep collection deliberate.** Honor collection settings and opt-outs. Distinguish query-parameter names from values when checking what is sent. Keep form field values out of automatic form tracking, sanitize automatically reported URLs, and keep extra diagnostic requests such as 404 confirmation opt-in. Make changes to collection defaults explicit for review. -6. **Preserve browser and build compatibility.** Keep visitor-facing output ES5-compatible and respect feature boundaries such as event-free `light.js`. Build affected scripts from source and commit their generated distributions. Review source and build inputs first, using relevant generated output to verify those changes. Keep previously published pinned versions and their SRI bytes unchanged unless explicitly requested. +6. **Preserve browser and build compatibility.** Keep visitor-facing output ES5-compatible and respect feature boundaries such as event-free `light.js`. Build affected scripts from source to verify them, but leave `dist/` out of commits (see Dist). Review source and build inputs first, using relevant generated output to verify those changes. Keep previously published pinned versions and their SRI bytes unchanged unless explicitly requested. ## Validation and review