Where should we store Architecutre Decision Records

[gfellerph]

An Architecture Decision Record (ADR) is a document that captures an important architecture decision made along with its context and consequences.

At the moment, we have a loose collection of Discussions, Issues, Contribution Guidelines, Comments on Pull Requests or Discussions in other Channels like Miro where decisions on architecture were taken. I'd like to store them in a central place.

Requirements

• Easy to create
• Has an edit history
• Easy to search/find
• Can be created by anyone
• Has a template for new decisions
• [optional] Support for comments

Where should we store them?

Internal Wiki

[+] Post employees can contribute, comment or react
[+] Easy to search
[+] Version history provided

[-] Disconnected from code
[-] Not public
[-] References can't provide quick information (issue pop-ups), just regular links

[?] Can a template be provided?

Markdown files in the repo

[+] Right in the repo, commit history
[+] Public, everyone with a GitHub account can contribute
[+] Template via example file
[+] Seems to be popular in the industry

[-] Harder to find, search only via generic code search
[-] Can't label nor comment
[-] Only developers can contribute

As issues on GitHub

[+] Lives on the repo, easy to find via issue search
[+] Can be added to project board for overview
[+] Everyone (not only devs) can create, comment, react, label and history is provided
[+] Easy possibility for templates

[-] Could be confusing because issues are not primarily meant for documentation
[-] Neither closing (harder to find) nor keeping ADR issues open (spamming other boards) is really ideal

As discussions on GitHub

[+] Lives on the repo, easy to find via discussion search
[+] Can create a new category for ADRs, but no template
[+] Everyone can create, comment, label and edit history is provided

[-] Not possible to create templates

On the GitHub Wiki page

[+] Lives on the repo, everyone can contribute, easy to find via wiki search
[+] Possibility to create index page as an overview

[-] Wiki seems not to be in focus for new features (better side navigation), can be handled with manual workarounds
[-] No possibility for templates, an example page can be provided

[alizedebray]

The categories and sections of GitHub Discussions can also help us keeping this decisions well organized.