Skip to content
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

[Issue 145] Update ADR template and process #146

Merged
merged 3 commits into from
Jul 7, 2023
Merged

[Issue 145] Update ADR template and process #146

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
122532e
refactor(github): Updates ADR issue template
widal001 Jul 7, 2023
6a7ee57
feat(adr): Outlines process for ADRs
widal001 Jul 7, 2023
f4f8dd5
refactor(adr): Updates list of statuses in template
widal001 Jul 7, 2023
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
19 changes: 13 additions & 6 deletions .github/ISSUE_TEMPLATE/adr.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: ADR
name: ADR
description: Record an architectural decision about the project
title: "[ADR]: "
labels: ["docs: adr"]
Expand All @@ -20,6 +20,13 @@ body:
description: 1-2 sentence summary of the decision that needs to be made
validations:
required: true
- type: textarea
id: approvers
attributes:
label: Approvers
description: List individuals or groups that must approve this decision before the ADR is accepted
validations:
required: false
- type: textarea
id: options
attributes:
Expand All @@ -40,10 +47,10 @@ body:
label: Definition of Done
description: Leave the following acceptance criteria unchecked when the ticket is created then mark them as completed as you meet each criterion with the ADR
options:
- label: The ADR is drafted and stored in `documentation/decisions/adr`
- label: The ADR is included in the necessary table of contents in the ADR/decision folder
- label: The ADR describes the drivers and pros and cons of the decision
- label: The ADR has been reviewed and approved by the internal team
- label: The approvers for this decision have been identified (ideally before work on the ADR starts)
- label: The ADR is created and stored in `documentation/decisions/adr` with status "Accepted"
- label: The ADR has been reviewed and approved by the approvers listed above
- label: The ADR satisfies requirements that are outlined in the ADR template
- label: Any follow-up tickets have been created (if necessary)
validations:
required: true
required: true
Copy link
Contributor

Choose a reason for hiding this comment

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

Woops. I apparently did not have a trailing whitespace extension enabled.

9 changes: 8 additions & 1 deletion documentation/decisions/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,14 @@ While architecture decisions come in all shapes and sizes, some common examples

## ADR Process

TODO: Create an ADR for proposing, approving, and accepting an ADR.
When an architectural decision needs to be recorded, please use the following steps:

1. [Create a new ADR ticket in GitHub](https://github.com/HHS/grants-equity/issues/new/choose)
2. Identify the approvers for this decision, i.e. individuals or groups who must sign off on the decision before the ADR can be accepted (ideally this happens before work starts on the ADR)
3. Draft an ADR in a branch named after the ticket, then open a Pull Request (PR)
4. Invite the approvers to review the PR and provide feedback or approve the decision
5. Once the approvers have signed off on the decision, merge the PR into the `main` branch with status "Accepted"
6. Create any follow-up tickets that are needed to implement the decision outlined in the ADR (if necessary)

## Acknowledgements and Further Reading

Expand Down
2 changes: 1 addition & 1 deletion documentation/decisions/adr/0001-recording-architecture-decisions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ _What is the best way to document key architectural decisions made within the pr

## Options Considered

- ADRs in the repo `docs/` folder
- ADRs in the repo `documentation/decisions/adr` folder
- Comments and docstrings in the code itself
- Articles in the project's Wiki

Expand Down
2 changes: 1 addition & 1 deletion documentation/decisions/template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# {short title of solved problem and solution}

- **Status:** {Draft | Proposed | Rejected | Accepted | Deprecated | ... | Superseded By [xxx](yyyymmdd-xxx.md)} <!-- REQUIRED -->
- **Status:** {Accepted | Deprecated | ... | Superseded By [xxx](yyyymmdd-xxx.md)} <!-- REQUIRED -->
- **Last Modified:** {YYYY-MM-DD when the decision was last updated} <!-- REQUIRED -->
- **Related Issue:** [#{issue number}](https://github.com/HHS/grants-api/issues) <!-- RECOMMENDED -->
- **Deciders:** {list everyone involved in the decision} <!-- REQUIRED -->
Expand Down