From 8ffb6607696cc08a22f87154a8b8478d19ea3c57 Mon Sep 17 00:00:00 2001 From: George Lund Date: Thu, 2 Nov 2023 13:29:11 +0000 Subject: [PATCH 1/3] Update guidance for making and documenting architectural decisions - describe a working ADR process/lifecycle that uses GitHub - note that tracking implementation is important - mention that other architecture document styles are available and important too --- .../architecture-decisions.html.md.erb | 90 +++++++++++++++++-- 1 file changed, 83 insertions(+), 7 deletions(-) diff --git a/source/standards/architecture-decisions.html.md.erb b/source/standards/architecture-decisions.html.md.erb index 1f564013..cee6e902 100644 --- a/source/standards/architecture-decisions.html.md.erb +++ b/source/standards/architecture-decisions.html.md.erb @@ -1,6 +1,6 @@ --- title: Documenting architecture decisions -last_reviewed_on: 2022-11-25 +last_reviewed_on: 2023-11-02 review_in: 6 months --- @@ -19,10 +19,6 @@ make. For example, understanding whether a particular choice was made for the sake of expediency and can therefore be changed with little impact, or whether there were external reasons behind that decision that need to be factored in. -In a new project or one with a lot of decisions to be made, consider setting up -regular ADR discussion and review meetings. This will give the team time to work -though these decisions. - ## How to document decisions Architecture decisions should be stored in version control so there is a @@ -30,13 +26,93 @@ record of what was changed, who by, and when. Decisions that affect a specific application should be in that application's code repository. You may also want to store larger-scale decisions in a central documentation repository. -A suggested format is the Architecture Decision Record, proposed by Michael +A suggested format is the Architecture Decision Record (ADR), proposed by Michael Nygard in [a blog post](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) and since adopted widely. That post describes the format in full, but as a summary it consists of the following sections: * **Title**: a description of the decision (not the problem) -* **Status**: for example, Proposed, Accepted, or Superseded +* **Status**: see [lifecycle](#lifecycle-of-an-adr) * **Context**: the facts behind the need to make the decision * **Decision**: what the team has decided to do * **Consequences**: both positive and negative consequences of the decision + +Amazon Web Services (AWS) also provide +[useful advice](https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/welcome.html) +about how and why the ADR process should be adopted. + +## Lifecycle of an ADR + +In a new project or one with a lot of decisions to be made, consider setting up +regular ADR discussion and review meetings. This will give the team time to work +though these decisions. + +Each decision goes through the following phases. + +### "Proposed" status + +Assuming you're using GitHub for version control, there is no need to record a 'status' for +an ADR when it is first proposed. +The status of your ADR's pull request (PR) reflects the status of the decision until it has been +accepted. + +Consider using GitHub's "draft PR" feature especially if you have lots of decisions at varying +levels of readyness. + +It's important to find the right group of reviewers for your ADR. +Ensure that you have input from all relevant technical disciplines (such as site reliability +engineers, developers, security architects, etc) and from any teams that might be affected. + +Some programmes use technical writers to ensure their ADRs meet our quality standards +and are as accessible to the widest audience possible. +Future team members that lack the full context you have for a decision will appreciate your +efforts! + +### "Accepted" status + +Once an ADR has been accepted then teams may need to know about its existence long into the +future. +Think about how to make your ADRs discoverable, especially if they require more than just a +one-off set of code or infrastructure changes. + +Again, the "accepted" status doesn't need to be explicit in your document - it can be assumed that an +ADR in the `main` branch of your GitHub repository is accepted. +Otherwise, teams can get confused about the real status of a decision, as the ADR goes through +the pull request process! + +### Implementation + +In some cases there will be an implementation phase during which you may discover that the +decision was wrong, or needs to be amended. + +If there are clarifications, then updating your existing ADR may be appropriate. + +You might find additional consequences to your decision, so consider updating the Consequences section +to reflect your evolving understanding of the problem space. + +If a decision was never implemented at all, then as long as your reviewers and other stakeholders +agree then it may be appropriate to update your existing ADR with a new decision. + +However, if some implementation of the original decision has occurred, you should write a new ADR +to explain the new decision. + +Any ADRs that have not been fully implemented across all the relevant teams should be a topic for +your regular discussion and review meeting. + +Consider using your issue tracker to make sure that decisions you've made are followed through +and put into effect. +The work isn't done until the decision is implemented! + +### "Superseded" status + +If a decision has been superseded by another decision, the old ADR must be clearly marked as "superseded". + +A "Status: superseded" line should appear directly under the heading. Add a link to the new ADR as soon as +it's been accepted. + +## What an ADR is not + +An ADR isn't a complete description of a software system or architecture. + +Some teams use requests for comment (RFCs), wikis, team manuals, or other collaboration tools to document +their architecture, and these should be updated whenever a new ADR is accepted. From 479b83b7966974f47a9b2a9648eed5083a25ea9d Mon Sep 17 00:00:00 2001 From: George Lund Date: Tue, 14 Nov 2023 09:54:57 +0000 Subject: [PATCH 2/3] Spilling Co-authored-by: Rafal Proszowski --- source/standards/architecture-decisions.html.md.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/standards/architecture-decisions.html.md.erb b/source/standards/architecture-decisions.html.md.erb index cee6e902..8ba4ef53 100644 --- a/source/standards/architecture-decisions.html.md.erb +++ b/source/standards/architecture-decisions.html.md.erb @@ -45,7 +45,7 @@ about how and why the ADR process should be adopted. In a new project or one with a lot of decisions to be made, consider setting up regular ADR discussion and review meetings. This will give the team time to work -though these decisions. +through these decisions. Each decision goes through the following phases. From c9226c40cb115a217912701823c7244f69083f4b Mon Sep 17 00:00:00 2001 From: George Lund Date: Tue, 14 Nov 2023 09:55:06 +0000 Subject: [PATCH 3/3] Spilling Co-authored-by: Rafal Proszowski --- source/standards/architecture-decisions.html.md.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/standards/architecture-decisions.html.md.erb b/source/standards/architecture-decisions.html.md.erb index 8ba4ef53..966e01d2 100644 --- a/source/standards/architecture-decisions.html.md.erb +++ b/source/standards/architecture-decisions.html.md.erb @@ -57,7 +57,7 @@ The status of your ADR's pull request (PR) reflects the status of the decision u accepted. Consider using GitHub's "draft PR" feature especially if you have lots of decisions at varying -levels of readyness. +levels of readiness. It's important to find the right group of reviewers for your ADR. Ensure that you have input from all relevant technical disciplines (such as site reliability