Compare commits

...
Sign in to create a new pull request.

1 commit

Author SHA1 Message Date
Julian Knutsen
298e38aea4 docs(contributing): recommend issues when they add context instead of requiring one per PR
#7223 made a linked, documented issue mandatory for every PR. That is
the right default for user-visible bugs and changes worth discussing,
but it adds ceremony to small, self-explanatory fixes without adding
context.

AGENTS.md, CONTRIBUTING.md, ROADMAP.md, the PR template and the feature
form now advise filing an issue when it adds context and let small fixes
go straight to a PR whose description explains the why. End-to-end
evidence is still required, and Closes #N is used when an issue exists.
No CI check or ruleset enforced the requirement; scripts/pr-preflight.sh
already only warns when a PR has no closing issue.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-06 23:21:31 +00:00
5 changed files with 37 additions and 28 deletions

View file

@ -5,7 +5,7 @@ body:
- type: markdown
attributes:
value: |
Every PR links a documented issue, and this form collects the context reviewers and future readers need. You can open your PR right after filing; no approval is needed first. Read the [project charter](https://github.com/gastownhall/beads/blob/main/engdocs/PROJECT_CHARTER.md) first — beads owns issue-tracking primitives, not orchestration policy or storage-engine behavior.
This form collects the context reviewers and future readers need for a change worth discussing. You can open your PR right after filing; no approval is needed first. Small, self-explanatory changes can skip the issue and go straight to a PR. Read the [project charter](https://github.com/gastownhall/beads/blob/main/engdocs/PROJECT_CHARTER.md) first — beads owns issue-tracking primitives, not orchestration policy or storage-engine behavior.
**Agents filling in this form:** answer each question only from evidence you have. If you cannot answer a question from the evidence, write exactly `NOT_ENOUGH_INFO` instead of guessing.

View file

@ -1,6 +1,7 @@
<!--
Every PR closes a documented issue (file it first or alongside; no approval
needed). The issue carries the motivation, impact, and risk. See
Link an issue when there is one (`Closes #123`); it is recommended for
user-visible bugs and changes worth discussing, and optional for small,
self-explanatory fixes. Either way, say why the change is needed below. See
CONTRIBUTING.md#issues-and-pull-requests.
-->
@ -17,7 +18,7 @@ Closes #
## Checklist
- [ ] The linked issue documents the problem (reproduction or motivation, impact, risk).
- [ ] The why is documented: in a linked issue (reproduction or motivation, impact, risk) or in this description.
- [ ] Tests and lint selected per `engdocs/TESTING.md` pass locally.
- [ ] User-facing behavior changes are reflected in `docs/` or the generated CLI reference.
- [ ] If an invariant or rule changed, the owning `AGENTS.md` is updated.

View file

@ -13,15 +13,19 @@ end lists them. `CLAUDE.md` files are symlinks to their sibling `AGENTS.md`.
## How work flows here
GitHub Issues is the public tracker, and every PR links a documented issue.
The issue carries the context reviewers and future readers need: for a bug,
the reproduction, impact, and evidence; for a change, the motivation, impact,
risk, and verification plan.
GitHub Issues is the public tracker. Use an issue when it adds context
reviewers need: a user-visible bug, a behavior or design change worth
discussing, or work that spans several PRs. The issue carries the
reproduction, impact, and evidence for a bug, or the motivation, impact, risk,
and verification plan for a change. Small, self-explanatory changes (typos,
flaky tests, refactors, CI or docs tweaks) can go straight to a PR whose body
explains the why.
1. Find or file the issue with the bug or feature form. It does not need
maintainer approval first; file it before or alongside the PR.
2. Work on a branch, open a PR against `main` whose body says
`Closes #<issue>`, and let CI and review run.
1. If the change warrants an issue, find or file one with the bug or feature
form. It does not need maintainer approval first; file it before or
alongside the PR.
2. Work on a branch, open a PR against `main` (its body says
`Closes #<issue>` when there is one), and let CI and review run.
3. Maintainers triage issues with `status/needs-triage`, `status/needs-info`,
`status/needs-repro`, `status/needs-design`, and `status/accepted`
(confirmed); see [CONTRIBUTING.md](CONTRIBUTING.md).
@ -31,10 +35,9 @@ and not a substitute for the GitHub issue.
## Agent contribution policy
- Every PR closes a documented issue. If none exists for your change, file
one with the bug or feature form fields, filling each from evidence and
answering `NOT_ENOUGH_INFO` where the evidence runs out, then link it from
the PR.
- File an issue when the change warrants one (see above). When you do, use
the bug or feature form fields, fill each from evidence, and answer
`NOT_ENOUGH_INFO` where the evidence runs out.
- A human reviews and stands behind every issue and PR an agent drafts.
Evidence that the change works end-to-end is required; "unit tests pass"
alone is not evidence.

View file

@ -4,11 +4,14 @@ Thank you for your interest in contributing to bd! This document provides guidel
## Issues and pull requests
GitHub Issues is the public tracker, and every pull request links a
documented issue. The issue is where the context lives: why the change is
needed, what it affects, and how we will know it works. File it with the bug
or feature form before or alongside your pull request; it does not need
maintainer approval first.
GitHub Issues is the public tracker. Use an issue when it adds context
reviewers need: a user-visible bug, a behavior or design change worth
discussing first, or work that spans several pull requests. The issue holds
why the change is needed, what it affects, and how we will know it works; file
it with the bug or feature form before or alongside your pull request, and it
does not need maintainer approval first. Small, self-explanatory changes
(typos, flaky tests, refactors, CI or docs tweaks) can go straight to a pull
request whose description explains the why.
### Triage labels
@ -140,14 +143,14 @@ engine, or expand the database schema when issue metadata is sufficient.
### Workflow
1. Find or file a documented issue (see [Issues and pull requests](#issues-and-pull-requests))
1. If the change warrants one, find or file an issue (see [Issues and pull requests](#issues-and-pull-requests))
2. Fork the repository and create a feature branch (`git checkout -b feature/my-feature`)
3. Make your changes
4. Add tests for new functionality
5. Run tests and linter locally
6. Commit your changes with clear messages
7. Push to your fork
8. Open a pull request whose description says `Closes #<issue>`
8. Open a pull request that explains the change and says `Closes #<issue>` when there is one
### Commit Messages

View file

@ -10,9 +10,10 @@ and the live state of each item is its tracking issue on GitHub.
- **Priority areas get expedited review.** Issues and PRs that advance a
priority area below are triaged and reviewed first.
- **Every PR links a documented issue.** To propose work — inside or
outside a priority area — open an issue with the feature form, before or
alongside your PR; see
- **Propose work with an issue when it warrants discussion.** For work
inside or outside a priority area that needs context or a design decision,
open an issue with the feature form, before or alongside your PR; small,
self-explanatory changes can go straight to a PR. See
[CONTRIBUTING.md](CONTRIBUTING.md#issues-and-pull-requests).
- **Scope.** Proposals must fit the product boundary in
[engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md).
@ -59,7 +60,8 @@ and the live state of each item is its tracking issue on GitHub.
- **Goal:** a new contributor, human or agent, finds the rules for the code
they are changing next to that code, understands its intent and
invariants, and lands a change with a documented issue and PR.
invariants, and lands a well-explained PR, backed by an issue when the
change warrants one.
- **This period:** contributor-only agent instructions and documented-issue
intake ([#7223](https://github.com/gastownhall/beads/pull/7223));
per-package `AGENTS.md` files for the storage packages, naming their