diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index b850c6595..5ab476fe9 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -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. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index a689ae380..0631bd36c 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,6 +1,7 @@ @@ -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. diff --git a/AGENTS.md b/AGENTS.md index a0cec3a42..5a0eabfff 100644 --- a/AGENTS.md +++ b/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 #`, 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 #` 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 24d3e573f..3fa5b2b03 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 #` +8. Open a pull request that explains the change and says `Closes #` when there is one ### Commit Messages diff --git a/ROADMAP.md b/ROADMAP.md index 214306136..006b5602e 100644 --- a/ROADMAP.md +++ b/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