Compare commits
1 commit
main
...
docs/issue
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
298e38aea4 |
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