feat: use PR number for ADR file naming to avoid collisions#25820
feat: use PR number for ADR file naming to avoid collisions#25820
Conversation
…erge=theirs for docs/adr/ Agent-Logs-Url: https://github.com/github/gh-aw/sessions/ad3fd267-2cea-4063-bb3a-0121fbb1e2a7 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Updates the ADR naming convention used by the Design Decision Gate workflow to use the pull request number (zero-padded) instead of an incrementing counter, aiming to prevent ADR filename collisions and reduce merge conflicts when multiple PRs generate ADRs concurrently.
Changes:
- Updated
design-decision-gate.mdinstructions/examples to use PR-number-based ADR filenames (e.g.,0042-...for PR #42). - Added a
.gitattributesrule intended to auto-resolve ADR merge conflicts viamerge=theirs.
Show a summary per file
| File | Description |
|---|---|
.github/workflows/design-decision-gate.md |
Switches ADR numbering guidance from incremental scanning to PR-number-based naming and updates examples/standards accordingly. |
.gitattributes |
Adds an ADR-specific merge attribute (docs/adr/*.md merge=theirs) to influence conflict resolution behavior. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 2/2 changed files
- Comments generated: 3
| ### 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 }}` |
There was a problem hiding this comment.
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.
| The PR number is: `${{ github.event.pull_request.number || github.event.inputs.pr_number }}` | ||
|
|
||
| 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`). |
There was a problem hiding this comment.
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.
| 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 |
There was a problem hiding this comment.
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.
| docs/adr/*.md merge=theirs | |
| docs/adr/*.md |
Summary
Updates the ADR file naming convention to use the pull request number instead of an incremental counter. This avoids file name collisions and merge conflicts when multiple PRs generate ADRs concurrently.
Changes
design-decision-gate.mdworkflow0042-use-postgresql.mdfor PR Add workflow: githubnext/agentics/weekly-research #42).gitattributesdocs/adr/*.md merge=theirsto automatically resolve merge conflicts in ADR files by accepting the incoming (PR branch) version. Since each PR creates a uniquely-named ADR file, this prevents merge conflicts when multiple PRs create ADRs concurrently.Why
merge=theirs?Each ADR file is uniquely named by PR number, so conflicts only arise if two branches modify the same file. The
merge=theirsstrategy means the incoming branch's version wins, which is correct because: