From 122532ed52ca076d1db51da68edf65f3097e080c Mon Sep 17 00:00:00 2001 From: widal001 Date: Fri, 7 Jul 2023 12:37:50 -0400 Subject: [PATCH 1/3] refactor(github): Updates ADR issue template - Adds an Approvers section - Updates the acceptance criteria --- .github/ISSUE_TEMPLATE/adr.yml | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/adr.yml b/.github/ISSUE_TEMPLATE/adr.yml index 25bcb73e5..ccf08e482 100644 --- a/.github/ISSUE_TEMPLATE/adr.yml +++ b/.github/ISSUE_TEMPLATE/adr.yml @@ -1,4 +1,4 @@ -name: ADR +name: ADR description: Record an architectural decision about the project title: "[ADR]: " labels: ["docs: adr"] @@ -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: @@ -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 From 6a7ee572a7313cfc7f40fa855dbd43d1c4b10137 Mon Sep 17 00:00:00 2001 From: widal001 Date: Fri, 7 Jul 2023 12:40:23 -0400 Subject: [PATCH 2/3] feat(adr): Outlines process for ADRs --- documentation/decisions/README.md | 9 ++++++++- .../adr/0001-recording-architecture-decisions.md | 2 +- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/documentation/decisions/README.md b/documentation/decisions/README.md index 55642392e..96b7e3c52 100644 --- a/documentation/decisions/README.md +++ b/documentation/decisions/README.md @@ -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 diff --git a/documentation/decisions/adr/0001-recording-architecture-decisions.md b/documentation/decisions/adr/0001-recording-architecture-decisions.md index 022983c80..69f4a8732 100644 --- a/documentation/decisions/adr/0001-recording-architecture-decisions.md +++ b/documentation/decisions/adr/0001-recording-architecture-decisions.md @@ -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 From f4f8dd5b30bf410628e0446364c6f975b79c4aca Mon Sep 17 00:00:00 2001 From: widal001 Date: Fri, 7 Jul 2023 12:43:11 -0400 Subject: [PATCH 3/3] refactor(adr): Updates list of statuses in template Removes Draft, Proposed, and Rejected status since those won't be merged --- documentation/decisions/template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/decisions/template.md b/documentation/decisions/template.md index a8d4a61de..c9e87b20f 100644 --- a/documentation/decisions/template.md +++ b/documentation/decisions/template.md @@ -1,6 +1,6 @@ # {short title of solved problem and solution} -- **Status:** {Draft | Proposed | Rejected | Accepted | Deprecated | ... | Superseded By [xxx](yyyymmdd-xxx.md)} +- **Status:** {Accepted | Deprecated | ... | Superseded By [xxx](yyyymmdd-xxx.md)} - **Last Modified:** {YYYY-MM-DD when the decision was last updated} - **Related Issue:** [#{issue number}](https://github.com/HHS/grants-api/issues) - **Deciders:** {list everyone involved in the decision}