Review and commit ADRs
An Architecture Decision Record (ADR) captures a decision and its reasons. ArchGuard drafts them so nobody starts from a blank page.
When a draft is created
A draft is created when a pull request introduces a new architectural pattern, a new external dependency, a database schema change or a new service contract, and the pull request does not already contain a file in the repository's ADR directory.
The pull request comment links to the draft. All pending drafts are listed under ADR drafts.
What a draft contains
Drafts follow the MADR format:
- Context and Problem Statement
- Decision Drivers
- Considered Options (with good and bad points)
- Decision Outcome
- Consequences
The draft is a starting point written by a language model from the diff. Treat it as a proposal: check the facts and the reasoning before approving.
Numbering
The number is the next one after the highest number found in the ADR directory on the target branch and in existing drafts. If another ADR takes the number before you approve, ArchGuard renumbers the draft when it commits.
Edit
Architects and Admins can change the title and the Markdown on a pending draft, and select Save changes. Viewers see the draft read-only.
Approve and commit
- Open the draft and select Approve & Commit ADR.
- ArchGuard commits
docs/adr/NNNN-title.mdto the pull request's source branch. If the pull request is already merged, it commits to the target branch instead. - The draft becomes approved committed, and the dashboard timeline shows the file path and commit.
Things to know:
- A double click commits once.
- A declined pull request cannot receive an ADR.
- If Bitbucket rejects the commit, the draft stays pending and you can try again. The message points at missing token scopes. See Connect Bitbucket Cloud.
Dismiss
Select Dismiss if the draft is not needed. Dismissed drafts cannot be approved later, but a new push that triggers a draft creates a fresh one.
Search
Approved ADRs appear in the timeline on the dashboard, where you can search titles and content.