mirror of
https://github.com/GSA/notifications-api.git
synced 2025-12-20 23:41:17 -05:00
Create custom ADR GitHub template(s) (#290)
This changeset adds a custom issue template and form for use within GitHub itself to help draft new Architectural Decision Records (ADRs). Note that we'll still ultimately have to create the actual ADR as a Markdown file that lives in the `doc/adrs/` folder. Signed-off-by: Carlo Costino <carlo.costino@gsa.gov>
This commit is contained in:
Carlo Costino
125
.github/ISSUE_TEMPLATE/create-a-new-adr.md
vendored
Normal file
125
.github/ISSUE_TEMPLATE/create-a-new-adr.md
vendored
Normal file
@@ -0,0 +1,125 @@
|
|||||||
|
---
|
||||||
|
name: Create a new ADR
|
||||||
|
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 | 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 | 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.
|
||||||
120
.github/ISSUE_TEMPLATE/create-new-adr-form.yml
vendored
Normal file
120
.github/ISSUE_TEMPLATE/create-new-adr-form.yml
vendored
Normal file
@@ -0,0 +1,120 @@
|
|||||||
|
name: Create a new ADR
|
||||||
|
description: Create a new Architectural Decision Record.
|
||||||
|
title: "[ADR]: "
|
||||||
|
labels: ["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
|
||||||
|
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
|
||||||
|
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
|
||||||
|
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:
|
||||||
|
label: Author
|
||||||
|
description: Who is the author(s) of this ADR?
|
||||||
|
placeholder: Enter your GitHub username here, and anyone else helping author this
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
- type: input
|
||||||
|
id: stakeholders
|
||||||
|
attributes:
|
||||||
|
label: Stakeholders
|
||||||
|
description: Who are the stakeholders of this ADR?
|
||||||
|
placeholder: Enter their GitHub username(s) here
|
||||||
|
validations:
|
||||||
|
required: false
|
||||||
|
- type: input
|
||||||
|
id: linked-github-issue
|
||||||
|
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.
|
||||||
|
validations:
|
||||||
|
required: false
|
||||||
Reference in New Issue
Block a user