Merge pull request #445 from GSA/stvnrlly/adr-workflow

Switch ADR workflow

.github/ISSUE_TEMPLATE/create-a-new-adr-from-template.md

@@ -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.

.github/ISSUE_TEMPLATE/create-new-adr-form.yml

@@ -1,59 +1,41 @@
 name: Create a new ADR
-description: Create a new Architectural Decision Record.
+description: Create a new issue with an ADR proposal
-title: "[ADR]: "
+labels: ["ADR: proposed", "documentation"]
-labels: ["documentation"]
 body:
   - type: markdown
     attributes:
       value: |
         Use this form to create a new Architectural Decision Record.
-  - type: input
+  - type: textarea
-    id: title
+    id: context
-    attributes:
-      label: ADR Title
-      description: What is the title of this ADR?
-      placeholder: e.g., Establishing ADRs for US Notify
     validations:
       required: true
-  - type: input
-    id: created_date
     attributes:
-      label: Created Date
+      label: Context
-      description: What is the date this ADR is being created?
+      description: >
-      placeholder: MM/DD/YYYY
+        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
+      label: Decision
-      description: What is the current status of this ADR?
+      description: >
-      options:
+        What was decided? This should be an active-voice statement. For example,
-        - Proposed
+        "We will use the US Web Design System." Note any major options that were
-        - Accepted
+        not selected.
-        - Rejected
+  - type: textarea
-        - Deprecated
+    id: consequences
-        - Superseded By
     validations:
       required: true
-  - type: dropdown
-    id: implemented
     attributes:
-      label: Implemented
+      label: Consequences
-      description: Is this ADR implemented?
+      description: >
-      options:
+        What are the consequences of this decision? Consequences can be
-        - 'Yes'
+        positive, negative, or neutral, but all known consequences of this
-        - 'No'
+        decision should be listed here.
-    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
   - type: input
     id: author
     attributes:
@@ -70,61 +52,12 @@ body:
       placeholder: Enter their GitHub username(s) here
     validations:
       required: false
-  - type: input
+  - type: textarea
-    id: linked-github-issue
+    id: next-steps
     attributes:
-      label: Related Issue(s)
+      label: Next Steps
-      description: List any related GitHub issues to this ADR here (issue number only).
+      description: >
-      placeholder: e.g., 288
+        Once option has already been chosen and justified, summarize or list the next steps
-    validations:
+        that came from the decision. Link to GitHub issues that track these steps.
-      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.
     validations:
       required: false

.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

docs/adrs/adr-template.md

@@ -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.