Hacker News Reader

I'm the repo maintainer. To answer your questions...

I recommend storing the ADRs as text files in a directory, such as `doc/adr`, or if you prefer words then `documentation/decisions`. Some teams prefer to use a wiki, or CMS, etc. and that can work well too.

I do recommend decision records as separate from git commit messages:

1. Easier for people to create, read, search, manage, sync, and audit. We use simple text formats, such as markdown.

2. Easier to generalize to multiple areas. For example, we use quick decision records to evaluate practices, tools, and techniques, across multiple projects and organizations. Participants don't always have access to the same git repos, and some participants don't even know git (e.g. finance, hard science companies, large enterprises).

3. Easier to update/append/eol when new information arrives. We revisit our decision records, such as when new technologies come into play, or when new requirements are created, or when we grow and want scalability, security, stability, etc. Appending to a text file is a piece of cake.

so what would the experience be for someone new joining the project, particular if you have many repositories? having to search across numerous repositories? In practice I've found this (source control commit messages as ADR's) doesn't work. Unless I have mistaken what you have said? I just keep a repository for ADR's, which can then be published to a wiki or else where.

In that situation, I think the best layout is:

- your centralised wiki lists all the repositories and explains what they’re for;

- each repository has a detailed commit history, allowing you to understand the thinking behind each line of code.

Edit to add: you can search across multiple repos with Github’s “search in organization” feature, and it actually works very well. I usually find that much more useful than searching through a wiki that’s separate from the code (although maybe I just haven’t ever seen a wiki that was sufficiently well organized?)

> each repository has a detailed commit history, allowing you to understand the thinking behind each line of code.

Ch ch ch changes

"Turn and face the strange" describes the git history of more than one project I've worked on...

If you make a habit of browsing your git log with -p or --numstat, you'll see the changes to the ADR show up.

> be unsure whether it’s still relevant.

The idea is that it's still relevant unless it's been marked superceded or deprecated.

> the history itself tells you whether those changes stuck around or were superseded.

Not really. The history has all of the changes, interleaved. So it's not easy for, looking at a commit message way in the past, to know whether a decision described there still applies to some later version.

I came to the same conclusion. I wanted to write ADRs since the first time I read about them a few years back. Thinking more about it I concluded that commit messages are the right place to document this. You can find the commit for a line of code and you can just read git log.

If people tried both and have opinions please share. So far I am ok with commit messages even if they tend to be long.

Another thing. How do you people think ADRs compare to design docs? IMO design docs are for gathering feedback and ADRs are for documenting decided things, there is some overlap.

I don't distinguish between the feedback gathering and the decision record. I collect feedback by integrating it into an ADR draft. Once the decision is made, the ADR is frozen and by construction includes the design documentation.

Most of the changes we (I work in a platform team) make may perhaps only modify a couple of lines of code, but took significant time and effort to reach.

As an example, we recently decided to adopt the use of Kubernetes CPU manager. The actual change was modifying the resource requests for some applications. That part of the code is highly dynamic as apps change and are retuned over time. To store the decision to use CPU manager in a commit message or even a Github PR would not be appropriate -- it's discoverability is too low compared to its importance.

Unlike Git commits or PRs, our ADRs are a rich archive of well thought out decisions with all the rationale that went into making them. We can easily see which ones remain relevant. But what I think is the most important is we have all the information we need to change our decisions and we do. We no longer fear making change because we might not have all the context, or we forgot, or the person who made the decision quit last year.