From cb97df080ef36817240323cf703bc4d6c67a852c Mon Sep 17 00:00:00 2001 From: Carlo Costino Date: Tue, 6 Jun 2023 15:35:56 -0400 Subject: [PATCH] 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 --- .github/ISSUE_TEMPLATE/create-a-new-adr.md | 125 ++++++++++++++++++ .../ISSUE_TEMPLATE/create-new-adr-form.yml | 120 +++++++++++++++++ 2 files changed, 245 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/create-a-new-adr.md create mode 100644 .github/ISSUE_TEMPLATE/create-new-adr-form.yml diff --git a/.github/ISSUE_TEMPLATE/create-a-new-adr.md b/.github/ISSUE_TEMPLATE/create-a-new-adr.md new file mode 100644 index 000000000..b1a96c0c1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/create-a-new-adr.md @@ -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. diff --git a/.github/ISSUE_TEMPLATE/create-new-adr-form.yml b/.github/ISSUE_TEMPLATE/create-new-adr-form.yml new file mode 100644 index 000000000..7a656e59c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/create-new-adr-form.yml @@ -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