Skip to content

feat: use PR number for ADR file naming to avoid collisions #25820

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 1 commit into from
Apr 11, 2026
+9 −9
Merged

feat: use PR number for ADR file naming to avoid collisions #25820

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitattributes
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ pkg/workflow/sh/*.sh linguist-generated=true
actions/*/index.js linguist-generated=true
actions/setup-cli/install.sh linguist-generated=true
specs/artifacts.md linguist-generated=true merge=ours
docs/adr/*.md merge=theirs
Copy link

Copilot AI Apr 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

merge=theirs is not a default/built-in Git merge driver in most Git setups; unless the repo also configures merge.theirs.driver for contributors/CI, this can cause merges to error with an unknown merge driver. Additionally, a “theirs” driver is directional (it always prefers the merged-in side), which can silently drop changes when merging main into a feature branch. Consider avoiding a custom driver here, or add explicit repository documentation/setup for the merge driver and confirm the directional behavior is acceptable.

Suggested change
docs/adr/*.md merge=theirs
docs/adr/*.md

Copilot uses AI. Check for mistakes.
# Use bd merge for beads JSONL files
.beads/issues.jsonl merge=beads
slides/*.pdf filter=lfs diff=lfs merge=lfs -text
Expand Down
17 changes: 8 additions & 9 deletions .github/workflows/design-decision-gate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ Search for a linked ADR in multiple locations:

### 3a. Check the PR Body
Look in the PR body for:
- A link to a file in `docs/adr/` (e.g., `docs/adr/0001-*.md`)
- A link to a file in `docs/adr/` (e.g., `docs/adr/NNNN-*.md` where NNNN is the PR number)
- A markdown link containing "ADR" or "Architecture Decision"
- A section labeled "ADR", "Design Decision Record", or "Architecture Decision Record"

Expand Down Expand Up @@ -145,14 +145,13 @@ An ADR is considered **present** if it contains all four required sections from

If no ADR is found, perform the following:

### Generate the Next ADR Number
### Determine the ADR Number

Check existing ADRs to determine the next sequence number:
```bash
ls ${{ github.workspace }}/docs/adr/*.md 2>/dev/null | grep -oP '\d+' | sort -n | tail -1
```
Use the **pull request number** as the ADR number. This avoids file name collisions and merge conflicts when multiple PRs generate ADRs concurrently.

The PR number is: `${{ github.event.pull_request.number || github.event.inputs.pr_number }}`
Comment on lines +148 to +152
Copy link

Copilot AI Apr 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This workflow is compiled into .github/workflows/design-decision-gate.lock.yml (which explicitly says it must be regenerated via gh aw compile). Since this PR changes the source .md, the corresponding .lock.yml should be updated in the same PR; otherwise the running GitHub Actions workflow will continue using the old compiled prompt and may also fail the built-in stale lock-file check.

Copilot uses AI. Check for mistakes.

If no ADRs exist, start at `0001`.
Format the number with zero-padding to 4 digits (e.g., PR #42 becomes `0042`, PR #1234 becomes `1234`).
Copy link

Copilot AI Apr 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The instructions rely on zero-padding to 4 digits, but PR numbers can exceed 9999. Elsewhere in this workflow the ADR list is lexicographically sorted (sort | tail -1), which will mis-order 5+ digit prefixes (e.g., 10000-... sorts before 9999-...). Consider either padding to a fixed width large enough for expected PR ranges, or switching the sort to a numeric/version sort so “most recent” selection remains correct.

Copilot uses AI. Check for mistakes.

### Analyze the PR Diff and Generate a Draft ADR

Expand Down Expand Up @@ -252,7 +251,7 @@ An ADR must contain these four sections to be considered complete:
- **Alternatives Considered** — What else could have been done?
- **Consequences** — What are the trade-offs (positive and negative)?

All ADRs are stored in `docs/adr/` as numbered Markdown files (e.g., `0001-use-postgresql.md`).
All ADRs are stored in `docs/adr/` as Markdown files numbered by PR number (e.g., `0042-use-postgresql.md` for PR #42).

</details>

Expand Down Expand Up @@ -364,7 +363,7 @@ When generating or reviewing ADRs, apply these quality standards based on the Mi
- **Decisive decision**: Use active voice. Say "We will use X because Y" not "X might be used."
- **Real alternatives**: List at least 2 genuine alternatives that were considered, not strawmen.
- **Balanced consequences**: Include both positive outcomes and genuine trade-offs.
- **Numbered and dated**: Filename format: `NNNN-kebab-case-title.md`. Always include the date.
- **Numbered by PR**: Filename format: `NNNN-kebab-case-title.md` where `NNNN` is the zero-padded pull request number. This avoids collisions when multiple PRs generate ADRs concurrently. Always include the date.

## Examples of ADR-Worthy Decisions

Expand Down
Loading