From 2117f31690595d8ab92d57f85c1397ef1b96b833 Mon Sep 17 00:00:00 2001 From: stvnrlly Date: Mon, 28 Aug 2023 21:04:26 -0400 Subject: [PATCH] add new adr workflow --- .../create-a-new-adr-from-template.md | 125 ------------------ .../ISSUE_TEMPLATE/create-new-adr-form.yml | 125 ++++-------------- .github/workflows/adr-accepted.yml | 18 +++ docs/adrs/adr-template.md | 116 ---------------- 4 files changed, 47 insertions(+), 337 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/create-a-new-adr-from-template.md create mode 100644 .github/workflows/adr-accepted.yml delete mode 100644 docs/adrs/adr-template.md diff --git a/.github/ISSUE_TEMPLATE/create-a-new-adr-from-template.md b/.github/ISSUE_TEMPLATE/create-a-new-adr-from-template.md deleted file mode 100644 index f94100417..000000000 --- a/.github/ISSUE_TEMPLATE/create-a-new-adr-from-template.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -name: Create a new ADR from template -about: Use this template to create a new Architectural Decision Record. -title: ADR -labels: documentation -assignees: '' - ---- - -# TITLE: ADR Title Here - - -| CREATED DATE | LAST UPDATED | STATUS | IMPLEMENTED | AUTHOR | STAKEHOLDERS | -| :---: | :---: | :---: | :---: | :---: | -| Date when ADR was created - MM/DD/YYYY format | Date when ADR was last updated - MM/DD/YYYY format - or N/A | Current ADR status - one of Proposed / Accepted / Rejected / Deprecated / Superseded By ADR - link to ADR | Yes or No | GitHub username(s) of author(s) | GitHub username(s) or team name(s) of other folks involved | - - -## CONTEXT AND PROBLEM STATEMENT - -**OPEN ISSUE(S):** Link(s) to related issue(s) here, if applicable. - -Explain the nature of the problem, challenge, or decision to be made here. Be as -succinct as possible, but don't leave out any details. State things matter of -factly and as objectively as you can. - - -## DECISION DRIVERS - -List anything that plays a major role in making a decision here. These could -be one or more of the following: - -- Desired qualities -- Desired outcomes -- Primary concerns -- Constraints -- ... (anything else pertinent to the decision-making process) - - -### SECURITY COMPLIANCE CONSIDERATIONS - -Because we work in a regulated space with many compliance requirements, we need -to make sure we're accounting for any security concerns and adhering to all -security compliance requirements. List them in this section along with any -relevant details: - -- Security concern 1 - - Concern detail 1 - - Concern detail 2 - - Concern detail ... - -- Security concern 2 - - Concern detail 1 - - Concern detail 2 - - Concern detail ... - - -## CONSIDERED OPTIONS - -List all options that have either been discussed or thought of as a potential -solution to the context and problem statement. Include any pros and cons with -each option, like so: - -- **Name of first option:** A brief summary of the option. - - Pros: - - Pro 1 - - Pro 2 - - Pro ... - - - Cons: - - Con 1 - - Con 2 - - Con ... - -- **Name of second option:** A brief summary of the option. - - Pros: - - Pro 1 - - Pro 2 - - Pro ... - - - Cons: - - Con 1 - - Con 2 - - Con ... - - -## PROPOSED OR CHOSEN OPTION: Proposed/Chosen Option Title Here - -Summarize the decision for the proposed/chosen option here. Be as concise and -objective as possible while including all relevant details so that a clear -justification is provided. Include a list of consequences for choosing this -option, both positive and negative: - - -### Consequences - -- Positive - - Positive consequence 1 - - Positive consequence 2 - - Positive consequence ... - -- Negative - - Negative consequence 1 - - Negative consequence 2 - - Negative consequence ... - - -## VALIDATION AND NEXT STEPS - -This section likely won't be filled out until a decision has been made by the -team and the ADR is accepted. If this comes to pass, then write up the criteria -that would ensure this ADR is both implemented and tested correctly and -adequately. This could be a short summary and/or a list of things: - -- **Criterion name 1:** Description of criterion 1 - - Requirement or action 1 - - Requirement or action 2 - - Requirement or action ... - -- **Criterion name 2:** Description of criterion 2 - - Requirement or action 1 - - Requirement or action 2 - - Requirement or action ... - -Lastly, include a link(s) to an issue(s) that represent the work that will -take place as follow-ups to this ADR. diff --git a/.github/ISSUE_TEMPLATE/create-new-adr-form.yml b/.github/ISSUE_TEMPLATE/create-new-adr-form.yml index 4f170c3db..5146a7082 100644 --- a/.github/ISSUE_TEMPLATE/create-new-adr-form.yml +++ b/.github/ISSUE_TEMPLATE/create-new-adr-form.yml @@ -1,59 +1,41 @@ name: Create a new ADR -description: Create a new Architectural Decision Record. -title: "[ADR]: " -labels: ["documentation"] +description: Create a new issue with an ADR proposal +labels: ["ADR: proposed", "documentation"] body: - type: markdown attributes: value: | Use this form to create a new Architectural Decision Record. - - type: input - id: title - attributes: - label: ADR Title - description: What is the title of this ADR? - placeholder: e.g., Establishing ADRs for US Notify + - type: textarea + id: context validations: required: true - - type: input - id: created_date attributes: - label: Created Date - description: What is the date this ADR is being created? - placeholder: MM/DD/YYYY + label: Context + description: > + Explain the nature of the problem, challenge, or decision to be made here. + Be as succinct as possible, but do not leave out any details. State things + matter of factly and as objectively as you can. + - type: textarea + id: decision validations: required: true - - type: dropdown - id: status attributes: - label: Status - description: What is the current status of this ADR? - options: - - Proposed - - Accepted - - Rejected - - Deprecated - - Superseded By + label: Decision + description: > + What was decided? This should be an active-voice statement. For example, + "We will use the US Web Design System." Note any major options that were + not selected. + - type: textarea + id: consequences validations: required: true - - type: dropdown - id: implemented attributes: - label: Implemented - description: Is this ADR implemented? - options: - - 'Yes' - - 'No' - validations: - required: true - - type: input - id: superseded_by - attributes: - label: Superseded By - description: If this ADR is superseded by another, which one is it? - placeholder: e.g., ADR-0001 - validations: - required: false + label: Consequences + description: > + What are the consequences of this decision? Consequences can be + positive, negative, or neutral, but all known consequences of this + decision should be listed here. - type: input id: author attributes: @@ -70,61 +52,12 @@ body: placeholder: Enter their GitHub username(s) here validations: required: false - - type: input - id: linked-github-issue + - type: textarea + id: next-steps attributes: - label: Related Issue(s) - description: List any related GitHub issues to this ADR here (issue number only). - placeholder: e.g., 288 - validations: - required: false - - type: textarea - id: context-and-problem-statement - attributes: - label: Context and Problem Statement - description: Explain the nature of the problem, challenge, or decision to be made here. - placeholder: Be as succinct as possible, but do not leave out any details. State things matter of factly and as objectively as you can. - validations: - required: true - - type: textarea - id: decision-drivers - attributes: - label: Decision Drivers - description: List anything that plays a major role in making a decision here. - validations: - required: true - - type: textarea - id: security-compliance-considerations - attributes: - label: Security Compliance Considerations - description: List any security concerns in this section along with any relevant details. - validations: - required: true - - type: textarea - id: considered-options - attributes: - label: Considered Options - description: List all options that have either been discussed or thought of as a potential solution to the context and problem statement. Include any pros and cons with each option. - validations: - required: true - - type: input - id: proposed-option - attributes: - label: Proposed Option - description: If an option is already clear or has been chosen, please name it here. - validations: - required: false - - type: textarea - id: proposed-option-justification - attributes: - label: Proposed or Chosen Option - description: Summarize the decision for the proposed/chosen option here, including a list of positive and negative consequences. - validations: - required: false - - type: textarea - id: validation-and-next-steps - attributes: - label: Validation and Next Steps - description: If an option has already been chosen and justified, summarize or list the validation and next steps that came from the decision. + label: Next Steps + description: > + Once option has already been chosen and justified, summarize or list the next steps + that came from the decision. Link to GitHub issues that track these steps. validations: required: false diff --git a/.github/workflows/adr-accepted.yml b/.github/workflows/adr-accepted.yml new file mode 100644 index 000000000..30caa7d30 --- /dev/null +++ b/.github/workflows/adr-accepted.yml @@ -0,0 +1,18 @@ +name: ADR accepted +on: + issues: + types: + - closed + +jobs: + main: + name: ADR accepted + runs-on: ubuntu-latest + + steps: + - name: memorialize the ADR + uses: 18F/adr-automation/accepted@v1 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + label: "ADR: accepted" + path: docs/adrs \ No newline at end of file diff --git a/docs/adrs/adr-template.md b/docs/adrs/adr-template.md deleted file mode 100644 index d2399af30..000000000 --- a/docs/adrs/adr-template.md +++ /dev/null @@ -1,116 +0,0 @@ -# TITLE: ADR Title Here - - -| CREATED DATE | LAST UPDATED | STATUS | IMPLEMENTED | AUTHOR | STAKEHOLDERS | -| :---: | :---: | :---: | :---: | :---: | -| Date when ADR was created - MM/DD/YYYY format | Date when ADR was last updated - MM/DD/YYYY format - or N/A | Current ADR status - one of Proposed / Accepted / Rejected / Deprecated / Superceded By ADR - link to ADR | Yes or No | GitHub username(s) of author(s) | GitHub username(s) or team name(s) of other folks involved | - - -## CONTEXT AND PROBLEM STATEMENT - -**OPEN ISSUE(S):** Link(s) to related issue(s) here, if applicable. - -Explain the nature of the problem, challenge, or decision to be made here. Be as -succinct as possible, but don't leave out any details. State things matter of -factly and as objectively as you can. - - -## DECISION DRIVERS - -List anything that plays a major role in making a decision here. These could -be one or more of the following: - -- Desired qualities -- Desired outcomes -- Primary concerns -- Constraints -- ... (anything else pertinent to the decision-making process) - - -### SECURITY COMPLIANCE CONSIDERATIONS - -Because we work in a regulated space with many compliance requirements, we need -to make sure we're accounting for any security concerns and adhering to all -security compliance requirements. List them in this section along with any -relevant details: - -- Security concern 1 - - Concern detail 1 - - Concern detail 2 - - Concern detail ... - -- Security concern 2 - - Concern detail 1 - - Concern detail 2 - - Concern detail ... - - -## CONSIDERED OPTIONS - -List all options that have either been discussed or thought of as a potential -solution to the context and problem statement. Include any pros and cons with -each option, like so: - -- **Name of first option:** A brief summary of the option. - - Pros: - - Pro 1 - - Pro 2 - - Pro ... - - - Cons: - - Con 1 - - Con 2 - - Con ... - -- **Name of second option:** A brief summary of the option. - - Pros: - - Pro 1 - - Pro 2 - - Pro ... - - - Cons: - - Con 1 - - Con 2 - - Con ... - - -## PROPOSED OR CHOSEN OPTION: Proposed/Chosen Option Title Here - -Summarize the decision for the proposed/chosen option here. Be as concise and -objective as possible while including all relevant details so that a clear -justification is provided. Include a list of consequences for choosing this -option, both positive and negative: - - -### Consequences - -- Positive - - Positive consequence 1 - - Positive consequence 2 - - Positive consequence ... - -- Negative - - Negative consequence 1 - - Negative consequence 2 - - Negative consequence ... - - -## VALIDATION AND NEXT STEPS - -This section likely won't be filled out until a decision has been made by the -team and the ADR is accepted. If this comes to pass, then write up the criteria -that would ensure this ADR is both implemented and tested correctly and -adequately. This could be a short summary and/or a list of things: - -- **Criterion name 1:** Description of criterion 1 - - Requirement or action 1 - - Requirement or action 2 - - Requirement or action ... - -- **Criterion name 2:** Description of criterion 2 - - Requirement or action 1 - - Requirement or action 2 - - Requirement or action ... - -Lastly, include a link(s) to an issue(s) that represent the work that will -take place as follow-ups to this ADR.