Strategic cooperation whereby different projects, groups or communities, while each operating independently, agree to collaborate and evolve an ecosystem collectively. They anticipate each other’s needs, align roadmaps, features, etc.
In the past I have worked with https://adr.github.io/ in professional settings. It proved to be useful using the wiki software that was provided by the client.
The elements are crucial:
Title (a summary to make it easier to search)
Timestamp (allows for assessing the relevance)
Status (e.g. proposed, accepted, rejected, deprecated, superseded)
Context (what is the environment in which a decision has to be made, constraints and similar)
Decision (out of several options which one is the way the team agreed to continue with?)
Consequences (what are the next action items caused by the decision)
Writing ADRs allows us to have a track record about decisions that were made in the past. Since I’m working in web frontend industry, this could be the decision on using SCSS vs. CSS-Modules vs. CSS-in-JS for example.
There were instances that made us reconsider a decision because the environment changed and we had to adapt. Having written down the context and possible options saved us time on research.
Institutionalising knowledge is also beneficial for team transitions (easier to onboard new people, less reliant on a single person and so on).
I looked at some templates e.g. the ones listed in this repo by Joel Henderson. There’s quite a big difference in formality, the amount of fields and information to track. Some lend themselves more for large organizations, multiple teams, complex software. For instance Decision record template by Jeff Tyree and Art Akerman would be overkill for most FOSS projects. There’s a big risk that the formality will lead to the documentation chore not happening.
ADRs should be stored within each software project repo
Create a separate repo for crosscutting ADRs
Track ADRs in the backlog
Review ADRs
Create ADRs for significant design decisions
The ADR markdown template itself is just as simple, having free-form text and a few paragraph sections. Here’s an example (click to expand):
ADR 005: Use a CQRS Pattern
ADR 005: Use a CQRS Pattern
We have a microservice architecture with several REST services that would need to read and write data.
Sometimes it’s difficult to design those services to do both tasks efficiently.
In the Farmacy Food system, the design of writes (commands) is primarily concerned with the integrity of data and business rules,
whereas the design of reads (queries) has performance (response time) as a key requirement.
Decision
We will use the CQRS pattern applied to microservices with this design:
an independently deployed service takes care queries. It reads data from a query view that is optimized for data reads.
(“Optimized” means using DB technologies and techniques that favor performance, such as: NoSQL, denormalized view, memory cache, sharding, replication.)
an independently deployed service takes care of commands. It may be a REST service that gets POST commands or a reactive service
that subscribes to a pub-sub topic and gets messages that updates the primary database for the scope of that service.
a batch component (example: K8S cron job or logic activated by database-triggered events) synchronizes the data between
the primary database and the query views. The frequency of data synchronization varies–it can be trigger-based,
every 5 minutes, every hour, …, once a day, etc.
In our design, we have used CQRS for:
Inventory
Orders
Subscription
Rationale
We expect that the app will issue far more query requests than commands. For example, the inventory is checked in many customer
operations, such as looking at a catalog meal item.
The CQRS pattern is used to address performance (response time)
requirements on queries.
Status
Proposed
Consequences
The CQRS pattern uses data replication for query views and hence eventual consistency. Therefore, query services may
operate on stale data (during the interval between data synchronization from primary db and query view).
Need to monitor data synchronization tasks, with notification and proper action in case of failure.
Only a bit more elaborate template is MADR, or Markdown Any Decision Records. It comes in a long and short form, listing options and where the long form indicates per option what is good and what is bad. MADR has several tools available for management (both for the CLI and a GH integration to make ADR management easier).
Some more examples of ADR’s in-the-wild. In this case using ADR’s for an open standard specification, namely JSON Schema. Here’s the issue on adopting ADR’s:
