adr / madr Goto Github PK

Please consider adding a branch for each major version to allow easy linking to the correct documents and template. e.g., stable-1, stable-2, stable-3.

This would allow linking to (for example) the latest 2.x template without pulling in 3.x features until we are ready for them.

Proposal: Remove the section about "Sustainable Architectural Decisions" in the README.md (https://github.com/adr/madr/blob/master/README.md#background-information).

Reason: Alternatives to the MADR are linked in the example file already. Also they they are mentioned on summary pages like https://adr.github.io and https://github.com/joelparkerhenderson/architecture_decision_record. Adding a section about alternatives within the MADR readme just lengthens the document and distracts the reader.

Solution: Remove the section.

Michael Nygard's template offers a Status field. See http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions. This should be supported by MADR, too. It should, however, be optional or less prominent to make it easier for newcomers. Maybe two variants of MADR?

adr-tools offers automatic setting of the status field. MADR, however, does not want to rely on tooling: It should be possible to create an ADR by just using copy'n'paste of template.md.

Greetings 👋 First just want to thank you for these awesome projects!

My team has been looking for a way to capture our decisions more consistently, and your tools and the processes they facilitate seem like an absolutely perfect fit. I'd anticipated that given our size we'd likely need to end up with a mechanism to categorize records, and I was encouraged by what I saw in https://github.com/adr/madr/blob/main/docs/decisions/0010-support-categories.md. However, IIUC the categorization feature appears to be future looking (ostensibly in the v3 beta release) so I have a few questions I'm hoping you can assist me with:

• Is the tooling support for categorization feature described in 0010 targeted for v3, or are there plans to include it in a v2 release?
• Do you have a ballpark target for when you think a v3 release may be published to npm (even an explicitly beta/prerelease version)?
• If we start using the v2 tooling today, would we be able to update to v3 seamlessly, or at least in an automated fashion, or would some manual work and changes be required?

Sometimes, one wants to write down an argument, which is neither pro nor con.

Options:

• OK, because ...
• Good/bad, because ...
• Interesting, because ...
• Neutral, because ...
• Indifferent, because

Example:

• The proposed solution is good, because it resolves the force 1.
• The proposed solution is good, because it addresses decision driver 2.
• The proposed solution is good, because it mitigates the technical risk / dept with respect to decision driver 4.
• The proposed solution is good, because it removes architectural smell ...
• The proposed solution is good, because it addresses stakeholder concern ...
• The proposed solution is good, because it has a positive effect on the performance (quality property).
• The proposed solution is neutral, because it is indifferent to decision driver 2.
• The proposed solution is bad, because it does not address decision driver 3.
• The proposed solution is bad, because it has a negative effect on the maintainability (quality property).

• The proposed solution is good with respect to resolving the force 1.
• The considered option is a good solution, because it resolves force1 and the non-resolving of force 1 is OK, ...

Real world example:

https://github.com/island-is/island.is/blob/main/handbook/technical-overview/adr/0005-error-tracking-and-monitoring.md

### Bugsnag

- Good, because it offers a Slack integration for faster feedback.
- Good, because it offers a Github integration to link to possible commits and PRs.
- Good, because it offers bot front-side/server-side/serverless error tracking.
- OK, because it was ranked the **\#5** as the best Javascript (client-side) error logging service in a community survey.
- Bad, because it's expensive. (**\$199/mo** for **450k events** and **15 collaborators**)
- Bad, because it's pricing includes a fixed set of collaborators.

In the paper Architectural Decision Guidance across Projects by Olaf Zimmermann, Lukas Wegmann, Heiko Koziolek and Thomas Goldschmidt, it is distinguished between "problem space" and "solution space"

Currently, we offer "MADR" as concept for the "solution space", where concrete solutions are written down. In addition, it can be abstracted from the solution space to the "problem space" to offer a collection of solutions, where one can pick from.

For instance: Concidered Options: "Maven, Gradle, Ant". They all have their "global" pros and cons. When going "locally", i.e., to a concrete project, new pros/cons are added and one option is chosen. Moreover, a context is added. -- That means, the format of the "global MADRs" differs from the format of the "local MADRs".

Question: How should the "global MADRs" be called?

Current thoughts:

The MADR template was pushed to the popular architecture_decision_record repository recently.

This template however has a different format for the User Story, than documented in here…

Current MADR template:

• https://github.com/adr/madr/blob/master/template/template.md

  User Story: [ticket/issue-number]

Pushed MADR template:

• https://github.com/joelparkerhenderson/architecture_decision_record/blob/master/adr_template_madr.md

  User Story: [ticket/issue-number]

I like the changes in the pushed template. May I prepare a PR to add this change to this repository?

See page 18 and 19 of http://www.iso-architecture.org/42010/templates/42010-ad-template.pdf

What happened to them? I don't see a discussion about their removal in either the changelog or adrs. I always found them to be the most important part of the template.

Refs adr/adr-manager#155

The "c" should be capitalized for "Negative consequences" in the template.

Quoting https://stackoverflow.com/a/7115411/873282

Do we need Assumptions, Constraints, Risk and Issues?

Depends on how detailed / formal you want to be. In terms of a Decisions Register we'd normally use one doc per area / decision, although recently we've been experimenting with OneNote.

At the very least you want to record (for each option):

• Option Description
• Pros and Cons
• Risks and Issues
• Assumptions and Constraints
• Points of Note

A succinct bullet-point list of pros & cons (etc) is usually sufficient - it doesn't need to be a big doc.

For a more in-depth / formal / complex scenario you'd want to go further, this is the format we were using in such cases:

Summary

• Problem Definition
• Solution Context
• Assumptions
• Constraints

Evaluation Criteria

(This is important as it sets out the criteria you used to score the available options, including weightings etc).

Summary of Recommendations

• Summary
• High-Level Comparison Table (This is good for providing an "at a glance" comparison for people who don't want to read a long document; and having a side-by-side comparison is a good idea anyway).

[Option 1…N]

• Option Description
• Pros and Cons
• Risks and Issues
• Assumptions and Constraints
• Points of Note

Recommendation

When installed, the bot checks whether template.md is outdated. It creates a PR if so.

Similar to https://dependabot.com/

The current adr-tools support (npryce/adr-tools#43) uses tables to describe links.

Currently, I lean towards adding the links at the bottom of a MADR.

Considered Options

• Use tables
• Use heading together with a bullet list directly after status
• Use heading together with a bullet list directly after "Decision Outcome"
• Use heading together with a bullet list at the end
• Don't do it

See https://github.com/adr/madr/blob/master/template/template.md for the current template.

Pros and Cons of the Options

Use tables

• Good, because easy to write
• Good, because history is shown (enabled by concept)
• Bad, because not supported by the CommonMark spec
• Bad, because unclear whether a link was superseeded by another one
• Bad, because valid links not clear at first sight (there might be outdated links shown)

Use heading together with a bullet list directly after status

Example:

• Good, because easy to write
• Good, because supported by the CommonMark spec
• Bad, because not consistent with the status label (refs #2)

Use heading together with a bullet list directly after "Decision Outcome"

• Similar to "directly after status"
• Good, because the options are first introduced and then the links
• Good, because consistent with position of "Decision Outcome"

Use heading together with a bullet list at the end

• Good, because the options and pros/cons are kept together with the option list.
• Good, because consistent with pattern format

Don't do it

• Good, because template stays minimal

https://github.com/joelparkerhenderson/architecture-decision-record/tree/main/templates/decision-record-template-madr

See https://medium.com/olzzio/adr-any-decision-record-916d1b64b28d for the reasoning

Follow-up to #92.

See thomvaill/log4brains#12 for details

• <!-- markdownlint-disable no-duplicate-heading --> MD024, because the option name is sometimes used as title of the ADR

Maybe put .markdownlint.yaml file aside

Miro gets more and more important. What if ADRs are brainstormed using miro and then markdown files are generated by a tool.

1. Create Miro template
2. Create converter tool

Unable to load user documentation at https://adr.github.io/madr/ -- 404. Is this a known issue?

D:\>curl -I https://adr.github.io/madr/
HTTP/1.1 404 Not Found

Coming from the discussion of status at #2 and seeing https://stackoverflow.com/a/7115411/873282, we should think of template-lean.md and template-full.md.

Zimmermann et al. compared other templates at https://www.ifs.hsr.ch/fileadmin/user_upload/customers/ifs.hsr.ch/Home/projekte/ADMentor-WICSA2015ubmissionv11nc.pdf:

One large repository

• Add categories to the ADRs (refs #7)
• Offer a web-based viewer

Several repositories

In addition

• there is an overarching repository collecting the ADRs of the sub repositories using git submodules
• there is a web-based tool for browsing.

In many CHANGELOG.md templates, there is a reference back to the template itself so that when I create a true instance of the CHANGELOG.md, someone can read it and know where to go to find the template it was created from to create another instance. I'd like to see this in the template for MADR.

See https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md

The website lists a fork of adr-tools as the suggested tool for a more automated approach to using MADR, however the PR was rejected and closed, and the fork is now archived, marked as superseded by log4brains (https://github.com/thomvaill/log4brains).

As such, does it make sense to update the docs on the website to link straight there?

@GitbookIO deletes comments when synchronizing with GitHub. Thus, our <!-- optional --> markers get lost. Maybe, it's time for template.md and template-advanced.md. (or template-min.md and template-max.md). Without placeholders, but other syntax highlighting possiblities.

Can we just use ADRs instead of Design docs/RFCs for large change proposals? This will save people the effort of writing a design doc and then also recording the design doc or RFC outcome as an ADR, which seems a bit cumbersome.

See http://www.************.com/markdown-style-guide/#option-list-marker-hyphen.

This is required for large repositories (refs #10)

e.g. ADR Manager?

The autogenerated TOC has no trailing newline.

This is problematic if you run a markdown linter that lints according to the commonmark spec. Since we autogenerate (adr -u) the TOC and we do linting in a continuous integration context this always fails.

A flag for adr -u to add a newline after generation would be useful.

README.md:3 MD047/single-trailing-newline Files should end with a single newline character

(deleted)

As written in the summary this repository “provides an initial directory structure and files to document Architectural Decisions using Markdown and Architectural Decision Records.”

The files (= the template) are explained in the README, the directory structure however is not. It's just presumed in the section Create a new ADR.
It would be nice to explain that the directory structure uses NNNN-title-with-dashes.md format and why it does so (other ADRs styles for example recommend using YYYY-MM-DD Title without Dahes or YYYY-MM-DD-title-with-dashes, so this difference should be explained somewhere).

Currently, I think https://chirpy.cotes.page/ seems to be better to present MADR. The current theme does not support TOCs (just-the-docs/just-the-docs#625). And it seems that the page does not look that well on wide screens.

Users are confused that the main page does not display the full template any more (#93).

Regarding #3 I just asked myself: How can I identify which version of MADR was used in a repository?

Idea: Suggest as best practice to document the version of MADR which was used initially. For example in the Initial decision file. So that somebody who writes a ADR may decide "We will use MADR in version 1.3.0 to document ADRs" and later "We update all existing ADRs to follow MADR version 2.0.18" etc.
Alternative: Add the version to the template file.

What do you think?

"Outcome" has "Positive Consequences" and "Negative Consequences" sections. "Options" just have a single list with "Good" and "Bad" prefixes.

• Good, because "Options" are denser.
• Bad, because the design is not consistent.
• Bad, because, if you first document options and then decide, one cannot just copy/paste, but rather one must change the design.

Example - source: https://github.com/archivematica/archivematica-architectural-decisions/blob/main/0000-use-markdown-architectural-decision-records.md

---
layout: page
status: accepted
adr: "0000"
title: Use Markdown Architectural Decision Records
deciders:
date:
---

## Context and problem statement

We want to record architectural decisions made in this project.
Which format and structure should these records follow?

## Considered options

* [MADR][0] 2.1.2 – The Markdown Architectural Decision Records
* [Michael Nygard's template][1] – The first incarnation of the term "ADR"
* [Sustainable Architectural Decisions][2] – The Y-Statements
* Other templates listed at @joelparkerhenderson's [repository][3].
* Formless – No conventions for file format and structure

## Decision outcome

Chosen option: "MADR 2.1.2", because

* Implicit assumptions should be made explicit.
  Design documentation is important to enable people understanding the decisions
  later on. See also [A rational design process: How and why to fake it][4].
* The MADR format is lean and fits our development style.
* The MADR structure is comprehensible and facilitates usage & maintenance.
* The MADR project is vivid.
* Version 2.1.2 is the latest one available when starting to document ADRs.

[0]: https://adr.github.io/madr/
[1]: http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
[2]: https://www.infoq.com/articles/sustainable-architectural-design-decisions
[3]: https://github.com/joelparkerhenderson/architecture_decision_record
[4]: https://doi.org/10.1109/TSE.1986.6312940

Rendered output:

Replace [option 1} by {option 1}.

Idea from https://github.com/tendermint/tendermint/blob/master/docs/architecture/adr-template.md

Example

{Deprecated|Proposed|Accepted|Declined}

Reason: Not conflicting with markdown

See https://ozimmer.ch/practices/2020/05/22/ADDefinitionOfDone.html for details

This is a checklist.

Is this a thing of MADR or a thing of ADR-Manager?

Example: https://github.com/elastic/cloud-on-k8s/tree/master/docs/design

Refs #33

Let's imagine that the latest number in the ADR numbering sequence is 5.
Dev A creates a PR with an ADR (he/she denotes that ADR with number 6).
Dev B creates a PR with an ADR (he/she denotes that ADR with number 6).
Dev A and Dev B merge at a different point in time.
Now we have two ADRs with different names but the same number.

One possible solution is to have a lock file that would contain the last number. We would have to increment this number each time we create a new ADR. This way after Dev A merges, Dev B can't merge due to conflict that needs to be resolved.
The con of this solution is that a Dev may forget to modify the lock file.

Are there any other propositions on solving this issue?

A template w/o the guiding comments, just the headings

We noticed an intersection between MADR and RACI, and felt the need to add a "consulted" and "informed" field in addition to "deciders". Would it be beneficial to "upstream" these fields to MADR?

• Check minimum example
• Add medium, and maximum example.
• Refine documentation: "Pick your style"

Refs #8

From template, section "More Information":

and/or define when this decision when and how the decision should be realized

Maybe https://github.com/red-hat-people-team/open-decision-framework helps?

(deleted)