Documenting Architectural Decisions Within Our Repositories

I recently discovered Michael Nygard's article on the subject of Documenting Architecture Decisions. I immediately became interested in using Architecture Decision Records (ADRs) with my projects.

I will provide a brief ADR summary, but I recommend reading Michael Nygard's article before continuing.

Table of Contents:

  1. An Overview of Architecture Decision Records
  2. Using ADRs in Your Projects
    1. Installation
    2. Initialization
    3. Creating a New ADR
    4. Linking ADRs
    5. Superseding ADRs
    6. Other adr-tools Tricks
      1. Listing ADRs
      2. Generating Summary Documentation
      3. Upgrading the ADR Document Format
  3. Putting it All Together
  4. Further Reading

An Overview of Architecture Decision Records

The motivation for using ADRs comes from a common scenario that all developers become familiar with:

One of the hardest things to track during the life of a project is the motivation behind certain decisions. A new person coming on to a project may be perplexed, baffled, delighted, or infuriated by some past decision. Without understanding the rationale or consequences, this person has only two choices:

1. Blindly accept the decision
2. Blindly change it.

Instead of leaving developers to operate blindly, we should record significant decisions affecting the structure, dependencies, interfaces, techniques, or other aspects of our code.

Rather than maintain a large document which nobody will read, we'll house these decisions within our repositories so they are easily accessible.

The ADR format summarizes decisions in five parts:

  1. Title
  2. Context
  3. Decision
  4. Status (e.g. proposed, accepted, deprecated, superseded)
  5. Consequences (good, bad, neutral)

ADR records should be kept short (maximum of two pages) so they are easily digestible by developers.

One ADR will document one significant decision. If a decision is reversed, amended, deprecated, or clarified, we'll keep the corresponding ADR. We'll generate a new ADR, link the related decisions together, and mark the previous decision with a relevant status note.

By keeping a full history of decisions, we help developers see the evolution of our decisions through time and provide the full context for each decision.

Now that we have a basic understanding of what an ADR is, let's see how we can use them in our projects.

Using ADRs in Your Projects

The free adr-tools project allows you to create and manage architecture decisions directly within your projects. No need to worry about managing yet-another-document in some-other-place-we-can't-remember.

ADRs are numbered in a sequential and monotonic manner (0001, 0002, 0003, …). The records are created as Markdown files so they can be parsed by GitHub and documentation tools.


adr-tools can be installed by adding the git project or a packaged release to your PATH.

Alternatively, OS X users can install adr-tools with Homebrew:

brew install adr-tools


Once adr-tools is installed, you will need to enable support inside of your repository using the adr init command. The command takes an argument which specifies where the ADRs should live. For example:

adr init doc/architecture/decisions

The adr init command will create the first ADR in your repository, which notes that you have decided to record architecture decisions:

# 1. Record architecture decisions

Date: 2018-03-20

## Status


## Context

We need to record the architectural decisions made on this project.

## Decision

We will use Architecture Decision Records, as described by Michael Nygard in this article:

## Consequences

See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's _adr-tools_ at

Creating a New ADR

To create a new ADR, use the adr new command:

adr new Title For My Decision

This will create a new decision record in the form of

If the VISUAL or EDITOR environment variables are set, the editor will automatically open the file. Otherwise you will need to manually open the file for editing.

Linking ADRs

You can link two ADRs together using the adr link command:


The SOURCE and TARGET arguments are references to an ADR, which can be either a number or partial filename. The LINK argument is a description that will be added the SOURCE ADR, and the REVERSE-LINK option is a description that will be added to the TARGET ADR.

For example, here is a link which indicates ADR 12 amends ADR 10:

adr link 12 Amends 10 "Amended by"

You can also link ADRs when creating a new one using the -l argument:


Similarly to the arguments for the adr link command, TARGET references the ADR which we are linking to, LINK is the description that will be added to our new ADR, and REVERSE-LINK is the description which will be added to the TARGET ADR.

To use our amendment example above:

adr new -l "12:Amends:Amended by" Brand New Decision

You can provide multiple -l options when creating a new ADR to enable linking to multiple existing records.

Superseding ADRs

When creating a new ADR, you can indicate that it supersedes an existing adr using the -s argument:

adr new -s 12 Brand New Decision

The status of the superseded ADR (0012 in the example above) will be updated to indicate that it superseded by the new ADR. The newly created ADR will also have a status which indicates the ADR that it is superseding.

You can provide multiple -s options when creating a new ADR.

Other adr-tools Tricks

While creating, linking, and superseding ADRs is primarily how we will interact with adr-tools, other options are available.

Listing ADRs

The adr list command will provide a list of all ADRs in your project:

$ adr list

Generating Summary Documentation

The adr generate command can be used to generate summary documentation. Two options are currently provided: toc and graph.

The toc argument will generate a Markdown-format table of contents:

$ adr generate toc
# Architecture Decision Records

* [1. Record architecture decisions](
* [2. Remove simulator from project](
* [3. Meson Build System](
* [4. Link With --whole-archive](

The graph argument will generate a visualisation of the links between decision records in Graphviz format. Each node in the graph represents a decision record and is linked to the decision record document.

$ adr generate graph
digraph {
  node [shape=plaintext];
  _1 [label="1. Record architecture decisions"; URL="0001-record-architecture-decisions.html"]
  _2 [label="2. Remove simulator from project"; URL="0002-remove-simulator-from-project.html"]
  _1 -> _2 [style="dotted"];
  _3 [label="3. Meson Build System"; URL="0003-meson-build-system.html"]
  _2 -> _3 [style="dotted"];
  _4 [label="4. Link With --whole-archive"; URL="0004-link-with-whole-archive.html"]
  _3 -> _4 [style="dotted"];

The link extension can be overridden with the -e argument. For example, to generate a PDF visualization which links to ADRs with PDF extensions:

adr generate graph -e .pdf | dot -Tpdf > graph.pdf

Upgrading the ADR Document Format

If the ADR format changes in a future adr-tools version, you can upgrade to the latest document format using the adr upgrade-repository command.

Putting it All Together

If you're curious about what ADRs look like in practice, I recommend reviewing the adr-tools decision records.

After trying out adr-tools and documenting my architecture decisions, I'm hooked. As a consultant, I frequently work on a variety of projects and am frustrated by the lack of documentation. I hope to leave other developers with the context for my decisions and prevent that frustration from spreading.

I encourage you to give ADRs a try. Keeping a list of running decisions in a simple and digestible manner is much easier than maintaining large specification documents.

Further Reading

Embedded Artistry CONTRIBUTING Template

In the last post we looked at the elements of a high-quality CONTRIBUTING guide. Today I'd like to share my CONTRIBUTING template with you.

This template is a starting point: feel free to add or remove sections based on the specifics of your project. Remember, you don't have to start with an amazing CONTRIBUTING guide. Covering the basics to help others get involved is enough, and more detail can be added as you answer questions and come across new situations.

You can always find this CONTRIBUTING template in the embedded-resources GitHub repository.

Embedded Artistry CONTRIBUTING Template

# Contributing

Write something nice and instructive as an intro. Talk about what kind of contributions you are interested in.

> Welcome! We love receiving contributions from our community, so thanks for stopping by! There are many ways to contribute, including submitting bug reports, improving documentation, submitting feature requests, reviewing new submissions, or contributing code that can be incorporated into the project.

This document describes our development process. Following these guidelines shows that you respect the time and effort of the developers managing this project. In return, you will be shown respect in addressing your issue, reviewing your changes, and incorporating your contributions.

If you're not looking for some kinds of contributions, note that up front:

> Please, don't use the issue tracker for support questions. Instead use: a, b, or Stack Overflow.

**Table of Contents:**

1. [Code of Conduct](#code-of-conduct)
2. [Important Resources](#important-resources)
2. [Questions](#questions)
3. [Feature Requests](#feature-requests)
4. [Improving Documentation](#improving-documentation)
5. [Reporting Bugs](#reporting-bugs)
6. [Contributing Code](#contributing-code)
    1. [Getting Started](#getting-started)
    1. [Finding an Issue!](#finding-an-issue)
    1. [Development Process](#development-process)
    1. [Building the Project](#building-the-project)
    1. [Testing](#testing)
    1. [Style Guidelines](#style-guidelines)
    1. [Code Formatting Rules](#code-formatting)
    1. [Whitespace Cleanup](#whitespace-cleanup)
1. [Pull Request Guidelines](#pull-request-guidelines)
    1. [Review Process](#review-process)
    1. [Addressing Feedback](#addressing-feedback)
1. [Community](#community)

## Code of Conduct

If you have a code of conduct document:

> By participating in this project, you agree to abide by our [Code of Conduct][0]. We expect all contributors to follow the [Code of Conduct][0] and to treat fellow humans with respect.

If not, lay some ground rules down up front.

## Important Resources

Include Short Links to Important Resources:

* docs: handbook / roadmap
* bugs: issue tracker / bug report tool
* comms: forum link, developer list, IRC/email
* wiki

## Questions

How do you prefer people to ask questions? Via an issue? Is there an IRC channel, google group, or other way to get help? Should issues that are questions get a specific label? Can they email you directly?

## Feature Requests

Provide information on the process for requsting new features. Do you have a specific label that should be applied? Is sign-off needed?

If you have a roadmap, goals, works in progress, or a development philosophy, make sure to share the information. Try to make sure that users have enough information to evaluate whether a feature request is appropriate for your project up front. Examples:

> Please create a new GitHub issue for any major changes and enhancements that you wish to make. Please provide the feature you would like to see, why you need it, and how it will work. Discuss your ideas transparently and get community feedback before proceeding.

> Major Changes that you wish to contribute to the project should be discussed first in an GitHub issue that clearly outlines the changes and benefits of the feature.

> Small Changes can directly be crafted and submitted to the GitHub Repository as a Pull Request. See the section about Pull Request Submission Guidelines, and for detailed information the core development documentation.

## Reporting Bugs

**If you find a security vulnerability, do NOT open an issue. Email EMAIL@DOMAIN.COM instead.**

Ask contributors to check before filing a new issue. Also, provide any references to FAQs or debugging guides that you might have.

> Before you submit your issue, please [search the issue archive][6] - maybe your question or issue has already been identified or addressed.

Tell contributors how to file a useful bug report. What information do you need? (e.g. version, architecture, log files, expected behavior, observed behavior).

> If you find a bug in the source code, you can help us by [submitting an issue to our GitHub issue tracker][6]. Even better, you can submit a Pull Request with a fix.

Does your project use an issue template? Provide instructions and expectations for filling it out.

Have you seen an awesome issue report? Link to it for others to view!

## Improving Documentation

Include notes for how users can improve the documentation.

> Should you have a suggestion for the documentation, you can open an issue and outline the problem or improvement you have - however, creating the doc fix yourself is much better!

> If you want to help improve the docs, it's a good idea to let others know what you're working on to minimize duplication of effort. Create a new issue (or comment on a related existing one) to let others know what you're working on. If you're making a small change (typo, phrasing) don't worry about filing an issue first.

> For large fixes, please build and test the documentation before submitting the PR to be sure you haven't accidentally introduced any layout or formatting issues.

Provide instructions on buildling and viewing documentation

## Contributing Code

This section is used to get new contributors up and running with dependencies, development, testing, style rules, formatting rules, and other things they should know.

If you have a label for beginner issues, talk about that here so they know where to look:

> Unsure where to begin contributing to Atom? You can start by looking through these beginner and help-wanted issues: Beginner issues - issues which should only require a few lines of code, and a test or two. Help wanted issues - issues which should be a bit more involved than beginner issues.

Working on your first open source project or pull request? Her are some helpful tutorials:

* [How to Contribute to an Open Source Project on GitHub][2]
* [Make a Pull Request][3]
* [First Timers Only][4]

### Getting Started

Install these dependencies:

with some examples

Provide some instructions for your workflow (e.g. fork the repository)

> You will need to fork the main repository to work on your changes. Simply navigate to our GitHub page and click the "Fork" button at the top. Once you've forked the repository, you can clone your new repository and start making edits.

> In git it is best to isolate each topic or feature into a “topic branch”. While individual commits allow you control over how small individual changes are made to the code, branches are a great way to group a set of commits all related to one feature together, or to isolate different efforts when you might be working on multiple topics at the same time.

> While it takes some experience to get the right feel about how to break up commits, a topic branch should be limited in scope to a single issue

# Checkout the master branch - you want your new branch to come from master
git checkout master

# Create a new branch named newfeature (give your branch its own simple informative name)
git branch newfeature

# Switch to your new branch
git checkout newfeature

For more information on the GitHub fork and pull-request processes, [please see this helpful guide][5].

### Finding an Issue

The list of outstanding feature requests and bugs can be found on our on our [GitHub issue tracker][6]. Pick an unassigned issue that you think you can accomplish and add a comment that you are attempting to do it.

Provide notes on different kinds of issues or labels

> `starter` labeled issues are deemed to be good low-hanging fruit for newcomers to the project
> `help-wanted` labeled issues may be more difficult than `starter` and may include new feature development
> `doc` labeled issues must only touch content in the `docs` folder.

### Development Process

What is your development process?

> This project follows the [git flow][8] branching model of product development.

Talk about branches people should work on. Sspecifically, where is the starting point? `master`, `development`, etc.

> You should be using the master branch for the most stable release; please review [release notes]( regularly. We do releases every week or two and send out notes. If you want to keep up with the latest changes, we work in the `dev` branch.  If you are using dev, keep an eagle-eye on commits and/or join our daily standup.

### Building the Project

What branches should be work be started off of?

Include instructions on how to build the project.

with some examples

Provide instructions on adding a new file/module to the build

with some examples

Keep your tests as simple as possible.

### Testing

If you add code you need to add tests! We’ve learned the hard way that code without tests is undependable. If your pull request reduces our test coverage because it lacks tests then it will be rejected.

Provide instructions for adding new tests. Provide instructions for running tests.

with examples

### Style Guidelines

If your code has any style guidelines, add them here or provide links to relevant documents. If you have an automated checker, make sure to provide instructions on how to run it.

### Code Formatting

If your code has any formatting guidelines that aren't covered in the style guidelines above, add them here.

If you're using an auto-formatting tool like clang-format

Provide instructions for running the formatting tool

### Whitespace Cleanup

Don’t mix code changes with whitespace cleanup! If you are fixing whitespace, include those changes separately from your code changes. If your request is unreadable due to whitespace changes, it will be rejected.

> Please submit whitespace cleanups in a separate pull request.

### Git Commit Guidelines

Do you have any guidelines for your commit messages? Include them here.

> The first line of the commit log must be treated as as an email
subject line.  It must be strictly no greater than 50 characters long.
The subject must stand on its own and not only make external
references such as to relevant bug numbers.

> The second line must be blank.

> The third line begins the body of the commit message (one or more
paragraphs) describing the details of the commit.  Paragraphs are each
separated by a blank line.  Paragraphs must be word wrapped to be no
longer than 76 characters.

> The last part of the commit log should contain all "external
references", such as which issues were fixed.

> For further notes about git commit messages, [please read this blog post][7].

## Pull Request Process

Do you have any labelling conventions?

Add notes for pushing your branch:

> When you are ready to generate a pull request, either for preliminary review, or for consideration of merging into the project you must first push your local topic branch back up to GitHub:

git push origin newfeature

Include a note about submitting the PR:

> Once you've committed and pushed all of your changes to GitHub, go to the page for your fork on GitHub, select your development branch, and click the pull request button. If you need to make any adjustments to your pull request, just push the updates to your branch. Your pull request will automatically track the changes on your development branch and update.

1. Ensure any install or build dependencies are removed before the end of the layer when doing a
2. Update the with details of changes to the interface, this includes new environment
   variables, exposed ports, useful file locations and container parameters.
3. Increase the version numbers in any examples files and the to the new version that this
   Pull Request would represent. The versioning scheme we use is [SemVer](
4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you
   do not have permission to do that, you may request the second reviewer to merge it for you.

### Review Process

Who reviews it? Who needs to sign off before it’s accepted? When should a contributor expect to hear from you? How can contributors get commit access, if at all?

> The core team looks at Pull Requests on a regular basis in a weekly triage meeting that we hold in a public Google Hangout. The hangout is announced in the weekly status updates that are sent to the puppet-dev list. Notes are posted to the Puppet Community community-triage repo and include a link to a YouTube recording of the hangout. After feedback has been given we expect responses within two weeks. After two weeks we may close the pull request if it isn't showing any activity.

> Except for critical, urgent or very small fixes, we try to leave pull requests open for most of the day or overnight if something comes in late in the day, so that multiple people have the chance to review/comment.  Anyone who reviews a pull request should leave a note to let others know that someone has looked at it.  For larger commits, we like to have a +1 from someone else on the core team and/or from other contributor(s).  Please note if you reviewed the code or tested locally -- a +1 by itself will typically be interpreted as your thinking its a good idea, but not having reviewed in detail.

Perhaps also provide the steps your team will use for checking a PR. Or discuss the steps run on your CI server if you have one. This will help developers understand how to investigate any failures or test the process on their own.

### Addressing Feedback

Once a PR has been submitted, your changes will be reviewed and constructive feedback may be provided. Feedback isn't meant as an attack, but to help make sure the highest-quality code makes it into our project. Changes will be approved once required feedback has been addressed.

If a maintainer asks you to "rebase" your PR, they're saying that a lot of code has changed, and that you need to update your fork so it's easier to merge.

To update your forked repository, follow these steps:

# Fetch upstream master and merge with your repo's master branch
git fetch upstream
git checkout master
git merge upstream/master

# If there were any new commits, rebase your development branch
git checkout newfeature
git rebase master

If too much code has changed for git to automatically apply your branches changes to the new master, you will need to manually resolve the merge conflicts yourself.

Once your new branch has no conflicts and works correctly, you can override your old branch using this command:

git push -f

Note that this will overwrite the old branch on the server, so make sure you are happy with your changes first!

## Community

Do you have a mailing list, google group, slack channel, IRC channel? Link to them here.

> Anyone actively contributing to or using OpenOpps should join our [Mailing List](!forum/openopps-platform).
We also have a public Slack chat team. If you're interested in following along with the development process or have questions, feel free to [join us](

Include Other Notes on how people can contribute

* You can help us answer questions our users have here:
* You can help build and design our website here:
* You can help write blog posts about the project by:
* You can help with newsletters and internal communications by:

* Create an example of the project in real world by building something or
showing what others have built.
* Write about other people’s projects based on this project. Show how
it’s used in daily life. Take screenshots and make videos!

[0]: docs/
[6]: link/to/your/project/issue/tracker

Get Others Involved in Your Project with a CONTRIBUTING Guide

I recently shared a README Template and strategies for improving your project's README. The README's purpose is to introduce new users to your project and help them start using it.

Today we're going to take a look at another helpful introductory document: the CONTRIBUTING guide.

Every software project comes with its own particular development process, expectations, and rules. These processes and requirements differ widely among development teams. There many questions that can be answered differently for each project:

  • What information is needed when filing a new issue?
  • How can I get the log files?
  • Do you want people to file an issue before attempting a fix?
  • Are pull requests without corresponding issues acceptable?
  • How should new tests be added?
  • What are the requirements for accepting changes into master?
  • Are there any coding standards I need to follow?
  • What is the Pull Request review process?

Team leaders and project maintainers can use the CONTRIBUTING guide to communicate rules and processes for contributing to the project. Since the process and expectations are documented, contributors can verify ahead of time that they are submitting changes and issues properly. Also, because the guidelines are clearly defined, improper issues or pull requests can be quickly rejected with a reference to the CONTRIBUTING guidelines.

Benefits When Using GitHub

GitHub has built-in support for CONTRIBUTING files. Whenever someone opens a pull request or creates a new issue, a banner will be included with a link to your guidelines.

Make sure that your CONTRIBUTING file is located in your repository root, docs folder, or .github folder. GitHub supports CONTRIBUTING files with no extension, a .txt extension, or a .md extension.


It's Never Too Early!

Often new projects will skip the documentation steps because they "don't need it yet." However, others can't contribute to your great project if you don't provide the resources to get them started.

In the early stages of a project, a simple CONTRIBUTING guide will probably suffice. You probably don't need strict processes yet. That's ok! Simply start with the basics and document your development setup and tell others what kind of contributions you are seeking. Over time your CONTRIBUTING guide should evolve to address problem areas, commonly asked questions, and new processes.

A Note About Formatting

Just like I said about your README, if your CONTRIBUTING guide is disorganized and poorly formatted, nobody is going to give it the time of day.

Most readers in our present era will be viewing your CONTRIBUTING guide in their web browser. Organizing your CONTRIBUTING guide into well-organized sections, formatting text so it stands out, and including a table of contents should be a priority.

Familiarize yourself with basic Markdown syntax to properly format your document. Add links to other documents and include images.

Elements of a Good Contributing Guide

Contributing guides vary in their coverage and length. The actual material is greatly dependent on the details of your particular project, the kind of contributions you are seeking, and the processes that your team wants to use.

Instead of covering specifics, let's take a look at some essential elements that a good contributing guide covers. Afterward I'll provide links to CONTRIBUTING files from around the web.


It's always nice to start by welcoming interested contributors to your project. Thank them for considering your project and tell them that you are excited for their contributions.

The introduction is a good place to cover what kinds of contributions you are seeking. You don't have to waste anybody's time if there is a mismatch of interests.

You can also cover your roadmap, who is on the team, and how people can get in touch with you.

Table of Contents

A short document can likely get away without a table of contents, but providing one will make your document much more accessible to your contributors. Instead of scrolling to find the details they are searching for, they can just click on the relevant anchor link. If you are using Markdown, you can create anchor links to your headers:

## Table of Contents
1. [About the Project](#about-the-project)
1. [Project Status](#project-status)
1. [Getting Started](#getting-started)

# About the Project

## Project Status

# Getting Started

Code of Conduct

The internet can be a harsh place, so at some point you will want to decide on a code of conduct. If it's simple, you can include it directly in your contributing guide. If you have a separate CODE_OF_CONDUCT file, you should link to it here.

Protect your project by laying down good behavioral rules up front!

Important Resources

There are likely other resources that are available to people interested in contributing to your project. Make sure to include relevant instructions and links in your CONTRIBUTING guide.

Possibilities include:

  • API documentation
  • Other reference documents
  • Useful blog posts
  • Your issue tracker
  • Google group information
  • Slack channel
  • Email list

Also make sure that you tell people how they can ask questions or get help with your project.


All teams have processes, and you should document yours so contributors have a reference.

By documenting your processes, you provide contributors with helpful references to get started on your project. You also protect your own time, as you can reject or close items that do not comply with the project guidelines.

Try to cover the following common processes in your CONTRIBUTING guide:

  • How to get questions answered
  • How to request new features or enhancements
  • How to help improve documentation
  • How to report a bug
    • Describe information should be included and how can they find it
  • Submitting pull requests
    • How code will be reviewed/approved
    • How feedback is expected to be addressed
    • Expected response timeframes
  • Include links to high-quality bug reports or pull requests for other users to reference

Contributing Code

The meat of your guide should describe how other developers can start working on your project. You should provide all relevant details that someone would need to know in order to start working on your project.

Cover topics such as:

  • How to set up the development environment
  • How to find issues to work on
  • What is the development process for your project?
    • Is master the latest?
    • Is there a stable or develop branch?
  • How to build the project
    • How to add new modules or files to the build
  • How to test the project
    • Where to find tests
    • How to add new tests
  • Relevant style guidelines or code formatting rules

Link to Your CONTRIBUTING Guide!

Make sure to link to your CONTRIBUTING file from your README so more people see it. Remember: if you place the CONTRIBUTING file in your project’s repository, GitHub will automatically link to your file when a contributor creates an issue or opens a pull request.

Example Contributing Guides

Here are some high quality CONTRIBUTING guides to use as a reference:

Further Reading: