Architecture Decision Record

An ADR is a architecturally significant decision that there is a consensus to adhere to.

Most often it relates to decisions taken in the software development process that affects the software.

From this definition it is possible to delve into academia or heavy enterprise process management.

However.

For our intents a simple model is proposed with a simplified workflow based around Git and GitHub for reviewing, discussing, and accepting proposals as a group.

The intent of using a ADR process is:

1. Capture longer term strategic goals and intentions.

1. Create alignment between teams within the same function.

1. Benefit from shared practice and experience over time.

1. Avoid discussions that come up again and again.

• Create a proposal ADR
• Open a PR in the amedia/adr repo
• Advertise it to the group
  • Post a link to the PR in e.g. #fag-front
  • Mention it in a group meeting
• Once it has been discussed and accepted in the PR and all concerns have been addressed (not necessarily accomodated)
• Merge the PR and make it the consensus

The ADR template can be found here: https://github.com/amedia/adr/blob/master/ADR_TEMPLATE.md

The components of it are:

1. Title
2. Date
3. Status
4. Context
5. Decision
6. Consequences

Title and date are self-explanatory.

The *status* is the current status of the document, so it can change from "proposed" to "accepted" to "superseded".

The *context* should provide information on what motivates the decision or change.

The decision is what is being proposed, and the consequences goes into the trade-offs (good and bad).

Decisions should not be written in stone, but they should have some inertia in order to be a useful tool to prevent having the same discussion time and again.

The questions that should be answered when challenging an ADR include:

• Have any fundamental assumptions changed that voids the rationale of the decision ?

• Are the fundamental problems with the decision that were not known before ?

• Is the decision having a damaging effect that outweighs the benefits ?

There are different ways to write an ADR that ranges from hyper-specific to general.

All can be valid ADRs, but the longer lasting ones are usually the strategic and general decisions that needs to hold up over time to provide their full benefits.

Some examples:

• an ADR that commits us to use NPM over Yarn/PNPM allows us to create unified tooling that can make assumptions based on how NPM works.

• an ADR that we use Node and not Deno allows developers in the same function (frontend) to share experience, work across teams, and make suggestions and discussions more relevant to more people.

• an ADR that any frontend technology we use for browser facing applications should be able to output web components allows flexibility to use many different frameworks, but stops us from using ones that do not align with our long-term strategies.

• an ADR that all package.json files should have specific scripts and functions, e.g. build, lint, and test should be predictable even if one uses webpack to build and another uses esbuild.

Some bad examples would be:

• an ADR that states that we use ReSveltUI for all browser facing applications.

• an ADR that we commit to using PreBlackIt for code formatting.

• an ADR that we must have line-by-line coverage for all our code.

They are too specific and dogmatic to be useful as good guidelines. They are either impossible to follow in all situations, or will become outdated and/or obsolete, forcing the discussion to be revisited again.

It is better to have an ADR that supports the long-term strategic goal and allow developers to make the best choice that supports that goal for the time being.

It also makes it easier to enforce the ADR, and, as a bonus, harder to challenge.