From 4d4652dc86fbb40f0277209eaaa35551c7c6d494 Mon Sep 17 00:00:00 2001 From: Simple Analytics Codex Date: Thu, 15 Oct 2026 14:53:57 +0200 Subject: [PATCH 1/2] Document tracker compatibility and size priorities for agents --- AGENTS.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 57a0759..3703802 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,21 +1,23 @@ -# Agent Instructions +# Agent instructions -This repository contains the public scripts for Simple Analytics. When making changes keep the following points in mind. +Before working here, read the shared [Simple Analytics instructions](https://github.com/simpleanalytics/ide-config/blob/main/AGENTS.md) through the approved GitHub access method. Apply them alongside applicable parent and nested instructions; more specific instructions take precedence. -## Development +## Tracker changes -- Use **Node.js 22.16** (see `.nvmrc`). -- Run `npm run build` to compile the scripts. This generates the files in `dist/` which should be committed. -- Format code with Prettier before committing. You can run `npx prettier -w .` or validate with `npm run prettier`. +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. -## Testing +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. -- Execute `npm run test:unit` to run the unit tests -- When adding a new feature or fixing a bug, please add a test. -- For every change, run `npm run build` to ensure the test uses the latest compiled version. -- Ignore most files in the `dist/` directory when checking for diffs, just check `dist/latest/latest.dev.js` and `dist/latest/auto-events.js` (whichever is relevant). -- Only tests in `test/unit/` are relevant for the AI and agents (it can run without internet access). +3. **Prefer simple implementations.** Add fallbacks, polling, abstractions, or compatibility layers only for a demonstrated requirement. Respect explicitly accepted tradeoffs, especially for unused beta helpers, rather than adding speculative compatibility machinery. -## References +4. **Preserve website behavior.** Tracking must respect cancelled actions, existing handlers, form validation, submitter settings, modified clicks, new tabs, and downloads. Let the browser or website own navigation and submission; send tracking without forcing either action. -Most work happens in `src/` with `compile.js` creating the distributable versions. Read `README.md` for more details about contributing and running scripts locally. +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. + +## Validation and review + +7. **Verify affected behavior locally.** Use the Node and pnpm versions declared by the repository configuration and the commands available in `package.json`; see `README.md` for setup. For script changes, rebuild before focused before/after payload and browser-interaction checks. Follow the shared testing policy and ensure committed tests run with declared dependencies. Leave the full BrowserStack matrix to CI unless explicitly requested, and report local verification separately from remote CI. + +8. **Keep PRs easy to review.** Prefer one logical change per PR. Group related fixes under one issue, state dependencies and merge order, and branch from and target the integration branch requested by the user. Keep unrelated test-infrastructure repairs separate from tracker behavior changes. From 04d7aee397663c4c5e1da24500ba07e7700794a6 Mon Sep 17 00:00:00 2001 From: Adriaan <1079135+adriaandotcom@users.noreply.github.com> Date: Thu, 15 Oct 2026 15:07:00 +0200 Subject: [PATCH 2/2] Update AGENTS.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 3703802..b785a1b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,6 +18,6 @@ Before working here, read the shared [Simple Analytics instructions](https://git ## Validation and review -7. **Verify affected behavior locally.** Use the Node and pnpm versions declared by the repository configuration and the commands available in `package.json`; see `README.md` for setup. For script changes, rebuild before focused before/after payload and browser-interaction checks. Follow the shared testing policy and ensure committed tests run with declared dependencies. Leave the full BrowserStack matrix to CI unless explicitly requested, and report local verification separately from remote CI. +7. **Verify affected behavior locally.** Use the Node and pnpm versions declared by the repository configuration and the commands available in `package.json`; see `README.md` for setup. For script changes, rebuild before focused before/after payload and browser-interaction checks. Prefer the offline suites in `test/unit/` for local runs. Follow the shared testing policy and ensure committed tests run with declared dependencies. Leave the full BrowserStack matrix to CI unless explicitly requested, and report local verification separately from remote CI. 8. **Keep PRs easy to review.** Prefer one logical change per PR. Group related fixes under one issue, state dependencies and merge order, and branch from and target the integration branch requested by the user. Keep unrelated test-infrastructure repairs separate from tracker behavior changes.