Agent instructionsScan: pass

AGENTS.md for Open Source Maintainers

AGENTS.md for a public OSS repo: issue linking, changelog entries, test requirements, CLA/DCO sign-off, and PR template compliance.

License: CC0-1.0 · By waxmark · v1 · 2026-11-02

Share on X

Add a trust badge to your README

[![Waxmark](https://waxmark.app/api/badge/agents-md-for-open-source-maintainers)](https://waxmark.app/items/agents-md-for-open-source-maintainers/scan)
Report
# 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.
AGENTS.md for Open Source Maintainers · Waxmark