docs: adopt issue#-prefix naming for ADRs/PRDs to eliminate parallel-developer collisions (#3487)
* docs: adopt issue#-prefix naming for ADRs/PRDs (#3485) The repo's sequential ADR/PRD numbering convention has produced recurring collisions when developers compute "next number" locally and ship in parallel — currently visible on disk as duplicate docs/adr/0010-*.md and triplicate docs/adr/0011-*.md, plus a stack of "resolve ADR conflict" commits in git history. Replace the local-compute convention with issue#-prefix slug naming: docs/adr/<issue#>-<slug>.md (new ADRs) docs/prd/<issue#>-<slug>.md (new PRDs — directory introduced) GitHub issue numbers are server-assigned and atomic, so the reservation step the CONTRIBUTING.md issue-first rule already enforces also produces the artifact ID. One issue = one ADR-or-PRD = one PR. Same shape as the existing changeset random-name pattern (#2975) for CHANGELOG.md fragments, applied to a different artifact class. Migration policy: legacy ADRs 0001-* through 0011-* are preserved as immutable historical record. The new convention applies only to ADRs/PRDs created on or after this merge. Files updated: - docs/adr/README.md — naming convention + legacy note + link - docs/prd/README.md (new) — seeds the new directory + same convention - CONTRIBUTING.md — new "Proposing an ADR or PRD" section - docs/contributor-standards.md — formalize as contributor requirement No code surface — docs-only. Closes #3485 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(changeset): add Changed fragment for ADR/PRD naming convention (#3487) Per CONTRIBUTING.md "When unsure whether a change is user-facing, add the fragment" — the contributor process IS user-facing for the contributor user class. Drop the no-changelog opt-out, surface the naming-convention change in the next CHANGELOG so contributors see it before they hit it as a PR rejection. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: address CodeRabbit findings on #3487 - CONTRIBUTING.md: rename heading to "Proposing an ADR or PRD" so its GitHub-anchor slug matches the #proposing-an-adr-or-prd link target used from docs/adr/README.md, docs/prd/README.md, and docs/contributor-standards.md (broken anchors) - docs/adr/README.md, docs/prd/README.md, docs/contributor-standards.md: add `text` language tag to the new naming-convention fenced blocks to satisfy markdownlint MD040 Pre-existing untyped fences elsewhere in the touched files are left alone per CONTRIBUTING.md "no drive-by formatting". Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
5
.changeset/zesty-goats-dart.md
Normal file
5
.changeset/zesty-goats-dart.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
type: Changed
|
||||
pr: 3487
|
||||
---
|
||||
**ADR and PRD files now use issue#-prefix slug naming** (`docs/adr/<issue#>-<slug>.md`, `docs/prd/<issue#>-<slug>.md`). The legacy local-compute sequential scheme (`NNNN-*`) is retained for the existing `docs/adr/0001-*` through `0011-*` files as immutable historical record but cannot be used for new ADRs/PRDs — collisions where two parallel PRs picked the same number prompted the change. See CONTRIBUTING.md "Proposing an ADR or PRD" for the full process.
|
||||
@@ -67,6 +67,30 @@ A feature adds something new — a new command, a new workflow, a new concept, a
|
||||
|
||||
---
|
||||
|
||||
### 📐 Proposing an ADR or PRD
|
||||
|
||||
An ADR (Architecture Decision Record) documents a significant architectural decision. A PRD (Product Requirements Document) captures the what and why of a feature before implementation. Both are governed by the same issue-first rule as everything else.
|
||||
|
||||
**Process:**
|
||||
|
||||
1. Open an issue of the appropriate type (enhancement for an ADR revisiting an existing area, feature for a new architectural surface, chore for policy/docs decisions). Fill it out completely.
|
||||
2. **Wait for maintainer approval.** A maintainer must label the issue `approved-enhancement`, `approved-feature`, or confirm the chore before any file is created.
|
||||
3. The GitHub-assigned issue number becomes your filename prefix. Create the file on a branch named after the issue:
|
||||
- `docs/adr/<issue#>-<slug>.md` for ADRs
|
||||
- `docs/prd/<issue#>-<slug>.md` for PRDs
|
||||
- Branch: `docs/<issue#>-<slug>`
|
||||
4. Open a PR using the appropriate template and close the issue with `Closes #<issue#>` in the PR body.
|
||||
|
||||
**One issue = one ADR-or-PRD = one PR.** Do not batch multiple decisions into one file or one PR.
|
||||
|
||||
**Do not compute a "next number" locally.** Any PR that uses the legacy `NNNN-*` sequential pattern for a *new* ADR or PRD will be asked to rename the file to the `<issue#>-<slug>.md` format before merge.
|
||||
|
||||
**Example:** Issue #3485 was opened, approved, and its number became the prefix: `docs/adr/3485-adr-prd-naming-convention.md` on branch `docs/3485-adr-prd-naming-convention`.
|
||||
|
||||
**Rejection reasons:** Issue not approved before file was created, filename uses local-compute sequential number instead of issue#, multiple decisions bundled in one PR, file placed in wrong directory (`docs/adr/` vs `docs/prd/`).
|
||||
|
||||
---
|
||||
|
||||
## The Issue-First Rule — No Exceptions
|
||||
|
||||
> **No code before approval.**
|
||||
|
||||
@@ -4,6 +4,28 @@ This directory contains Architecture Decision Records (ADRs) for GSD.
|
||||
|
||||
Each ADR documents one architectural decision: what was decided, why, and what consequences follow. ADRs are append-only. Amendments extend existing ADRs with a dated section rather than replacing them.
|
||||
|
||||
## Naming Convention
|
||||
|
||||
New ADRs use **issue#-prefix slug** naming:
|
||||
|
||||
```text
|
||||
docs/adr/<issue#>-<kebab-slug>.md
|
||||
```
|
||||
|
||||
Examples: `3485-adr-prd-naming-convention.md`, `3464-review-default-reviewers.md`.
|
||||
|
||||
### Why
|
||||
|
||||
Two developers computing "next ADR number" locally against `main` will independently pick the same integer and both ship. The collision is already on disk — `0010-*` exists twice and `0011-*` exists three times. GitHub issue numbers are server-assigned and atomic: the moment you open an issue, that number is reserved globally. Two PRs that both edit the `### Fixed` block of `CHANGELOG.md` always conflict on merge — two PRs that each use a distinct issue# as their ADR prefix never collide. Same shape, same solution.
|
||||
|
||||
### Legacy ADRs
|
||||
|
||||
Files `0001-*` through `0011-*` are preserved as immutable historical record. The duplicate `0010-*` and the three-way `0011-*` are documented residue of the old local-compute convention — not patterns to imitate. Do not renumber them.
|
||||
|
||||
### Full process
|
||||
|
||||
See **[CONTRIBUTING.md — "Proposing an ADR or PRD"](../../CONTRIBUTING.md#proposing-an-adr-or-prd)** for the end-to-end workflow: opening the issue, waiting for approval, naming the file, and submitting the PR.
|
||||
|
||||
## Index
|
||||
|
||||
| ADR | Title | Status |
|
||||
|
||||
@@ -89,7 +89,22 @@ An ADR is optional (a comment in the relevant issue or PR is sufficient) when:
|
||||
|
||||
### Naming conventions
|
||||
|
||||
`NNNN-<short-slug>.md` — four-digit zero-padded sequence number, followed by a kebab-case slug that names the Module or decision. Example: `0003-model-catalog-module.md`.
|
||||
**New ADRs and PRDs use issue#-prefix slug naming. This is a contributor requirement, not a suggestion.**
|
||||
|
||||
```text
|
||||
docs/adr/<issue#>-<kebab-slug>.md (new ADRs)
|
||||
docs/prd/<issue#>-<kebab-slug>.md (new PRDs)
|
||||
```
|
||||
|
||||
Example: `docs/adr/3485-adr-prd-naming-convention.md`.
|
||||
|
||||
**Why:** GitHub issue numbers are server-assigned and atomic — the reservation mechanism already exists because the issue-first rule requires it. Promoting the issue# to the artifact ID eliminates the entire collision class that the `NNNN-*` local-compute scheme created (see the `0010-*` × 2 and `0011-*` × 3 duplicates on disk).
|
||||
|
||||
**Migration policy:** Legacy ADRs `0001-*` through `0011-*` keep their numbers as immutable historical record. The new convention applies to all ADRs and PRDs created on or after the merge of the implementing PR (#3485). Do not renumber legacy files.
|
||||
|
||||
For the end-to-end workflow — opening the issue, waiting for approval, creating the file, and submitting the PR — see **[CONTRIBUTING.md — "Proposing an ADR or PRD"](../CONTRIBUTING.md#proposing-an-adr-or-prd)**.
|
||||
|
||||
The legacy four-digit scheme (`0003-model-catalog-module.md`) applies only to pre-existing files.
|
||||
|
||||
### Required sections
|
||||
|
||||
@@ -121,7 +136,7 @@ Reference sibling ADRs by filename, not by title prose: `see \`0001-dispatch-pol
|
||||
|
||||
### ADR README index
|
||||
|
||||
`docs/adr/` does not currently maintain a separate `README.md` index. The canonical index is the table in this document (above). If an ADR is added, update this table in the same PR.
|
||||
`docs/adr/README.md` maintains the canonical index table and the naming convention documentation. The table in this document (above) covers accepted ADRs for contributor reference. If an ADR is added, update both tables in the same PR.
|
||||
|
||||
### Governance
|
||||
|
||||
|
||||
27
docs/prd/README.md
Normal file
27
docs/prd/README.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# Product Requirements Documents
|
||||
|
||||
This directory contains Product Requirements Documents (PRDs) for GSD.
|
||||
|
||||
A PRD captures the **what** and **why** of a feature before implementation begins. ADRs (in `docs/adr/`) capture the **how** of architectural decisions. The two complement each other: a PRD makes the case for a feature and defines acceptance criteria; an ADR records the architectural mechanism chosen to deliver it.
|
||||
|
||||
## Naming Convention
|
||||
|
||||
PRDs use the same issue#-prefix slug naming as ADRs:
|
||||
|
||||
```text
|
||||
docs/prd/<issue#>-<kebab-slug>.md
|
||||
```
|
||||
|
||||
Example: `docs/prd/3491-bar-feature.md` for a feature tracked in issue #3491.
|
||||
|
||||
The GitHub-assigned issue number is the prefix. Do not compute a sequential number locally — see [CONTRIBUTING.md — "Proposing an ADR or PRD"](../../CONTRIBUTING.md#proposing-an-adr-or-prd) for the full process.
|
||||
|
||||
## Historical note
|
||||
|
||||
`docs/adr/0011-review-default-reviewers-prd.md` predates this directory and is preserved as immutable historical record. It is not a pattern to follow. New PRDs live here.
|
||||
|
||||
## Index
|
||||
|
||||
| PRD | Title | Status |
|
||||
|-----|-------|--------|
|
||||
| _(none yet — new PRDs use `<issue#>-<slug>.md` naming)_ | | |
|
||||
Reference in New Issue
Block a user