Raw view: AGENTS.md for Open Source Maintainers
No invisible, zero-width, or bidi-control characters detected.
# Contributing to {{PROJECT_NAME}} (agent instructions)
This repository is open source under {{LICENSE_NAME}}. Contributions are reviewed by volunteer maintainers. Every rule below exists to make review fast; follow them exactly. `CONTRIBUTING.md` has the human-oriented version.
## Setup
```sh
{{INSTALL_COMMAND}}
{{TEST_COMMAND}}
{{LINT_COMMAND}}
```
Both commands must exit 0 before you open or update a pull request. Paste their final output in the PR description under "Verification".
## Start from an issue
- Every PR references an issue. If none exists, open one first describing the problem (not the solution) and wait for a maintainer to label it `accepted` before writing code. Exception: typo and documentation fixes under 10 lines.
- The PR body's first line is `Fixes #<issue>` or `Refs #<issue>`. Use `Fixes` only when the PR fully resolves it.
- Do not combine unrelated issues in one PR. Do not start work on an issue assigned to someone else.
- Read the whole issue thread before coding; maintainers often constrain the approach in comments.
## Branch and commits
- Branch from `{{DEFAULT_BRANCH}}`, named `<type>/<issue>-<short-slug>`, for example `fix/1234-null-config`.
- Conventional Commits: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`, with an optional scope (`fix(parser): ...`). Subject under 72 characters, imperative mood.
- Sign off every commit with {{SIGNOFF_MECHANISM}}: for DCO, commit with `git commit -s` so the message ends in `Signed-off-by: Name <email>`; for a CLA, the bot will comment on the PR with the signing link. Do not sign on anyone's behalf.
- Rebase onto `{{DEFAULT_BRANCH}}` rather than merging it in. Squash fixup commits before marking the PR ready.
## Tests
- Bug fix: add a test that fails without the fix and passes with it. Name it after the issue where the convention allows (`test_issue_1234_null_config`).
- Feature: unit tests for the new API plus one integration or end-to-end test exercising the user-visible path.
- Never delete, skip, or loosen an existing test to make the suite pass. If a test is wrong, fix it in a separate commit and explain why in the PR.
- Keep tests deterministic: no network, no wall-clock sleeps, no reliance on test order.
## Changelog
- Add an entry to `CHANGELOG.md` under `## [Unreleased]` in the matching subsection (`Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`), one line, ending with the issue link: `- Fix crash when config is null (#1234)`.
- Write it for users, not developers: what changed for them, not which function moved.
- Documentation-only and test-only changes do not get an entry.
- If the repo uses Changesets or `towncrier` fragments instead, follow that mechanism and do not edit `CHANGELOG.md` directly.
## Pull request
- Use the template in `.github/PULL_REQUEST_TEMPLATE.md` verbatim. Fill every section; write `N/A` rather than deleting a heading.
- Title matches the Conventional Commit subject of the main change.
- Keep PRs under roughly 400 changed lines. Split larger work into a stacked series and say so in each description.
- Open as a draft until tests pass and the checklist is complete. Mark ready only once.
- Respond to every review comment: push a fix or reply with a reason. Do not resolve a maintainer's comment thread yourself.
- Do not force-push after review has started unless a maintainer asks; push fixup commits instead so the reviewer can see the delta.
## Scope and style
- Match existing code style; the linter is the authority. Do not reformat files you are not changing.
- No new runtime dependencies without prior agreement in the issue. New dev dependencies need a one-line justification in the PR.
- Public API changes (signatures, CLI flags, config keys, wire formats) need a deprecation path and a `Deprecated` changelog entry before removal; removal happens in a later major release.
- Update the docs (`docs/` or README) in the same PR as the behavior change.
## Do not
- Do not modify `LICENSE`, `CODEOWNERS`, `SECURITY.md`, release workflows, or version numbers; maintainers own those.
- Do not report security vulnerabilities in a public issue or PR; follow `SECURITY.md`.
- Do not add yourself to `AUTHORS` or similar lists unless the repo's `CONTRIBUTING.md` asks contributors to.
- Do not open a PR that only reformats, renames, or "cleans up" code without an accepted issue.