From 706331cf6cb387a5e163f47db1ea1046c5fc0837 Mon Sep 17 00:00:00 2001 From: Michael FIG Date: Mon, 23 Nov 2020 11:38:02 -0600 Subject: [PATCH 1/5] docs: create ADR-0001 --- .../0001-record-architecture-decisions.md | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs/architecture/0001-record-architecture-decisions.md diff --git a/docs/architecture/0001-record-architecture-decisions.md b/docs/architecture/0001-record-architecture-decisions.md new file mode 100644 index 00000000000..4cc7c828689 --- /dev/null +++ b/docs/architecture/0001-record-architecture-decisions.md @@ -0,0 +1,65 @@ +# 1. Record architecture decisions + +## Context + +*Evolved from [Michael Nygard's article on the subject](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions)* + +Architecture for agile projects has to be described and defined differently. Not all decisions will be made at once, nor will all of them be done when the project begins. + +Agile methods are not opposed to documentation, only to valueless documentation. Documents that assist the team itself can have value, but only if they are kept up to date. Large documents are never kept up to date. Small, modular documents have at least a chance at being updated. + +Nobody ever reads large documents, either. Most developers have been on at least one project where the specification document was larger (in bytes) than the total source code size. Those documents are too large to open, read, or update. Bite sized pieces are easier for for all stakeholders to consume. + +One of the hardest things to track during the life of a project is the motivation behind certain decisions. A new person coming on to a project may be perplexed, baffled, delighted, or infuriated by some past decision. Without understanding the rationale or consequences, this person has only two choices: + +1. Blindly accept the decision. + +This response may be OK, if the decision is still valid. It may not be good, however, if the context has changed and the decision should really be revisited. If the project accumulates too many decisions accepted without understanding, then the development team becomes afraid to change anything and the project collapses under its own weight. + +2. Blindly change it. + +Again, this may be OK if the decision needs to be reversed. On the other hand, changing the decision without understanding its motivation or consequences could mean damaging the project's overall value without realizing it. (E.g., the decision supported a non-functional requirement that hasn't been tested yet.) + +It's better to avoid either blind acceptance or blind reversal. + +## Decision + +We will keep a collection of records for "architecturally significant" decisions: those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques. + +An architecture decision record is a short text file in a format similar to an Alexandrian pattern. (Though the decisions themselves are not necessarily patterns, they share the characteristic balancing of forces.) Each record describes a set of forces and a single decision in response to those forces. Note that the decision is the central piece here, so specific forces may appear in multiple ADRs. + +We will keep ADRs in the project repository under doc/arch/adr-NNN.md + +We should use a lightweight text formatting language like Markdown or Textile. + +ADRs will be numbered sequentially and monotonically. Numbers will not be reused. + +If a decision is reversed, we will keep the old one around, but mark it as superseded. (It's still relevant to know that it was the decision, but is no longer the decision.) + +We will use a format with just a few parts, so each document is easy to digest. The format has just a few parts. + +**Title** These documents have names that are short noun phrases. For example, "ADR 1: Deployment on Ruby on Rails 3.0.10" or "ADR 9: LDAP for Multitenant Integration" + +**Context** This section describes the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts. + +**Decision** This section describes our response to these forces. It is stated in full sentences, with active voice. "We will …" + +**Status** A decision may be "proposed" if the project stakeholders haven't agreed with it yet, or "accepted" once it is agreed. If a later ADR changes or reverses a decision, it may be marked as "deprecated" or "superseded" with a reference to its replacement. + +**Consequences** This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future. + +The whole document should be one or two pages long. We will write each ADR as if it is a conversation with a future developer. This requires good writing style, with full sentences organized into paragraphs. Bullets are acceptable only for visual style, not as an excuse for writing sentence fragments. (Bullets kill people, even PowerPoint bullets.) + +## Status + +Accepted. + +## Consequences + +One ADR describes one significant decision for a specific project. It should be something that has an effect on how the rest of the project will run. + +The consequences of one ADR are very likely to become the context for subsequent ADRs. This is also similar to Alexander's idea of a pattern language: the large-scale responses create spaces for the smaller scale to fit into. + +Developers and project stakeholders can see the ADRs, even as the team composition changes over time. + +The motivation behind previous decisions is visible for everyone, present and future. Nobody is left scratching their heads to understand, "What were they thinking?" and the time to change old decisions will be clear from changes in the project's context. From a8d2acb286fd13b73f950ad64776d08416e04b4b Mon Sep 17 00:00:00 2001 From: Michael FIG Date: Mon, 23 Nov 2020 11:55:16 -0600 Subject: [PATCH 2/5] docs: update status section --- .../0001-record-architecture-decisions.md | 23 ++++++++++++------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/architecture/0001-record-architecture-decisions.md b/docs/architecture/0001-record-architecture-decisions.md index 4cc7c828689..efbca59b8da 100644 --- a/docs/architecture/0001-record-architecture-decisions.md +++ b/docs/architecture/0001-record-architecture-decisions.md @@ -1,8 +1,13 @@ -# 1. Record architecture decisions +# ADR 1: Record architecture decisions + +## Status + +Proposed - 2020-11-23 ## Context -*Evolved from [Michael Nygard's article on the subject](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions)* +*Almost verbatim from [Michael Nygard's article on the +subject](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions)* Architecture for agile projects has to be described and defined differently. Not all decisions will be made at once, nor will all of them be done when the project begins. @@ -40,20 +45,22 @@ We will use a format with just a few parts, so each document is easy to digest. **Title** These documents have names that are short noun phrases. For example, "ADR 1: Deployment on Ruby on Rails 3.0.10" or "ADR 9: LDAP for Multitenant Integration" +**Status** A decision may be "proposed" if the project stakeholders haven't +agreed with it yet, or "accepted" once it is agreed. If a later ADR changes or +reverses a decision, it may be marked as "deprecated" or "superseded" with a +reference to its replacement. We will append a date (in [ISO 8601 extended +format](https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates)) of when the +status changed, but other metadata will only be captured in the source +repository history. + **Context** This section describes the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts. **Decision** This section describes our response to these forces. It is stated in full sentences, with active voice. "We will …" -**Status** A decision may be "proposed" if the project stakeholders haven't agreed with it yet, or "accepted" once it is agreed. If a later ADR changes or reverses a decision, it may be marked as "deprecated" or "superseded" with a reference to its replacement. - **Consequences** This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future. The whole document should be one or two pages long. We will write each ADR as if it is a conversation with a future developer. This requires good writing style, with full sentences organized into paragraphs. Bullets are acceptable only for visual style, not as an excuse for writing sentence fragments. (Bullets kill people, even PowerPoint bullets.) -## Status - -Accepted. - ## Consequences One ADR describes one significant decision for a specific project. It should be something that has an effect on how the rest of the project will run. From 032119fb4316fa481ea772ba847bb5e1584c7f07 Mon Sep 17 00:00:00 2001 From: Michael FIG Date: Mon, 23 Nov 2020 12:13:52 -0600 Subject: [PATCH 3/5] docs: add adr-template.md --- .../0001-record-architecture-decisions.md | 18 +++++++------- docs/architecture/adr-template.md | 24 +++++++++++++++++++ 2 files changed, 33 insertions(+), 9 deletions(-) create mode 100644 docs/architecture/adr-template.md diff --git a/docs/architecture/0001-record-architecture-decisions.md b/docs/architecture/0001-record-architecture-decisions.md index efbca59b8da..ca900b6d5c8 100644 --- a/docs/architecture/0001-record-architecture-decisions.md +++ b/docs/architecture/0001-record-architecture-decisions.md @@ -1,14 +1,14 @@ # ADR 1: Record architecture decisions +*Taken almost verbatim from [Michael Nygard's article on the +subject](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions)* + ## Status -Proposed - 2020-11-23 +2020-11-23 - Proposed ## Context -*Almost verbatim from [Michael Nygard's article on the -subject](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions)* - Architecture for agile projects has to be described and defined differently. Not all decisions will be made at once, nor will all of them be done when the project begins. Agile methods are not opposed to documentation, only to valueless documentation. Documents that assist the team itself can have value, but only if they are kept up to date. Large documents are never kept up to date. Small, modular documents have at least a chance at being updated. @@ -45,13 +45,13 @@ We will use a format with just a few parts, so each document is easy to digest. **Title** These documents have names that are short noun phrases. For example, "ADR 1: Deployment on Ruby on Rails 3.0.10" or "ADR 9: LDAP for Multitenant Integration" -**Status** A decision may be "proposed" if the project stakeholders haven't -agreed with it yet, or "accepted" once it is agreed. If a later ADR changes or -reverses a decision, it may be marked as "deprecated" or "superseded" with a -reference to its replacement. We will append a date (in [ISO 8601 extended +**Status** We will start with a date (in [ISO 8601 extended format](https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates)) of when the status changed, but other metadata will only be captured in the source -repository history. +repository history. A decision may be "proposed" if the project stakeholders +haven't agreed with it yet, or "accepted" once it is agreed. If a later ADR +changes or reverses a decision, it may be marked as "deprecated" or "superseded" +with a reference to its replacement. **Context** This section describes the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts. diff --git a/docs/architecture/adr-template.md b/docs/architecture/adr-template.md new file mode 100644 index 00000000000..a45e948b95a --- /dev/null +++ b/docs/architecture/adr-template.md @@ -0,0 +1,24 @@ +# ADR [Number]: [Title] + +> *This template is derived from [ADR#1](./0001-record-architecture-decisions.md)* + +> These documents have names that are short noun phrases. For example, "ADR 1: Deployment on Ruby on Rails 3.0.10" or "ADR 9: LDAP for Multitenant Integration" + +## Status + +> [ISO 8601 Date] - Proposed + +## Context + +> This section describes the forces at play, including technological, political, +social, and project local. These forces are probably in tension, and should be +called out as such. The language in this section is value-neutral. It is simply +describing facts. + +## Decision + +> This section describes our response to these forces. It is stated in full sentences, with active voice. "We will …" + +## Consequences + +> This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future. From d1b99f887045bbe2179a13a4755941d8cd6d84b7 Mon Sep 17 00:00:00 2001 From: Michael FIG Date: Mon, 23 Nov 2020 12:29:59 -0600 Subject: [PATCH 4/5] docs: explain the consequence of a simple starting point --- docs/architecture/0001-record-architecture-decisions.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/architecture/0001-record-architecture-decisions.md b/docs/architecture/0001-record-architecture-decisions.md index ca900b6d5c8..5f50d875043 100644 --- a/docs/architecture/0001-record-architecture-decisions.md +++ b/docs/architecture/0001-record-architecture-decisions.md @@ -70,3 +70,7 @@ The consequences of one ADR are very likely to become the context for subsequent Developers and project stakeholders can see the ADRs, even as the team composition changes over time. The motivation behind previous decisions is visible for everyone, present and future. Nobody is left scratching their heads to understand, "What were they thinking?" and the time to change old decisions will be clear from changes in the project's context. + +Every requirement of the ADR format comes at the cost of more friction, so +starting with a simple structure is prudent. Refinements can be added in future +ADRs as agreed on by the team. From 20fe6c9eabdb83c3f6063d517940b4034aff60e8 Mon Sep 17 00:00:00 2001 From: Michael FIG Date: Sat, 30 Jan 2021 14:20:24 -0600 Subject: [PATCH 5/5] docs: add project and other relevant ADRs to Context --- docs/architecture/0001-record-architecture-decisions.md | 6 +++++- docs/architecture/adr-template.md | 1 + 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/architecture/0001-record-architecture-decisions.md b/docs/architecture/0001-record-architecture-decisions.md index 5f50d875043..cba0f81572c 100644 --- a/docs/architecture/0001-record-architecture-decisions.md +++ b/docs/architecture/0001-record-architecture-decisions.md @@ -53,7 +53,11 @@ haven't agreed with it yet, or "accepted" once it is agreed. If a later ADR changes or reverses a decision, it may be marked as "deprecated" or "superseded" with a reference to its replacement. -**Context** This section describes the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts. +**Context** Note the project to which this ADR applies, including other +relevant ADRs. This section describes the forces at play, including +technological, political, social, and project local. These forces are probably +in tension, and should be called out as such. The language in this section is +value-neutral. It is simply describing facts. **Decision** This section describes our response to these forces. It is stated in full sentences, with active voice. "We will …" diff --git a/docs/architecture/adr-template.md b/docs/architecture/adr-template.md index a45e948b95a..e666375eb7f 100644 --- a/docs/architecture/adr-template.md +++ b/docs/architecture/adr-template.md @@ -10,6 +10,7 @@ ## Context +> Note the project to which this ADR applies, including other relevant ADRs. > This section describes the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply