docs(contributing): recommend issues when they add context instead of requiring one per PR (#7323)
#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>
This commit is contained in:
parent
d4309098e5
commit
55f96b3f5e
5 changed files with 37 additions and 28 deletions
2
.github/ISSUE_TEMPLATE/feature_request.yml
vendored
2
.github/ISSUE_TEMPLATE/feature_request.yml
vendored
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
7
.github/PULL_REQUEST_TEMPLATE.md
vendored
7
.github/PULL_REQUEST_TEMPLATE.md
vendored
|
|
@ -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.
|
||||
|
|
|
|||
27
AGENTS.md
27
AGENTS.md
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
10
ROADMAP.md
10
ROADMAP.md
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue