Open Source Maintainer AGENTS.md

# AGENTS.md — Open Source Maintenance This repository publishes `<your-package>` to a public registry. People depend on it in production. The prime directive: **do not break users without a major version and a migration path.** ## What counts as public API - Everything exported from the package entry point(s) declared in `package.json` `exports` (or the documented top-level namespace for other ecosystems). - Documented CLI flags, config file keys, error codes/classes users are told to catch, and serialized formats we tell users to persist. - NOT public: anything under `internal/`/`_private`, undocumented behavior, exact error message strings, dependency versions. Still, check reverse dependencies before changing observable behavior — Hyrum's Law applies. When editing any public-facing signature, state in the PR description whether the change is **patch / minor / major** and why. ## Semver rules - **Patch**: bug fixes, docs, performance with identical behavior. - **Minor**: new exports, new optional parameters/config keys, widening accepted input. - **Major**: removals, renames, changed defaults, narrowing accepted input, raising the minimum runtime version, type changes that break downstream compiles. - A bug fix that users plausibly depend on (the bug was observable behavior for a long time) gets discussed in an issue before shipping — sometimes the fix is the breaking change. - Deprecate before removing: mark with `@deprecated` + the replacement in the doc comment, warn once at runtime where feasible, keep it working for at least one full minor release, list removal in the changelog's "Deprecations" section. ## Changelog - `CHANGELOG.md` follows Keep a Changelog headings: Added / Changed / Deprecated / Removed / Fixed / Security, newest release first, plus an Unreleased section. - Every user-visible PR adds an Unreleased entry **in the same PR** — entries are written for users ("`parse()` no longer throws on empty input"), not for contributors ("refactor parser internals" does not belong). - Each entry links the PR number and credits external contributors by handle. - Releases: move Unreleased under the new version + date, tag `v<version>`, and never rewrite a published entry — corrections get a new entry. ## Issue triage labels Apply exactly one type label and one status label on first triage: - Type: `bug`, `feature`, `docs`, `question`, `maintenance` - Status: `needs-repro` (no minimal reproduction yet), `confirmed`, `needs-decision` (maintainer call required), `help-wanted`, `good-first-issue` - Extra: `breaking` (fix requires a major), `regression` (worked in a prior release — prioritize and find the offending version with `git bisect` if needed) Triage replies: thank the reporter, ask for a minimal repro if missing (link the issue template), and never promise timelines. ## PR review checklist for agents 1. Tests cover the change, including the reported repro for bug fixes. 2. Public API diff reviewed — run `<your-api-report-tool>` (e.g. api-extractor) and commit the updated report. 3. Changelog entry present and user-facing. 4. No new runtime dependencies without maintainer sign-off; every new dependency is a supply-chain liability. 5. Docs/README examples updated if behavior they show changed. 6. CI green on all supported runtime versions in the matrix — do not drop a version from the matrix to make CI pass.