Introduction

adrs is a command line tool for creating and managing Architectural Decision Records. It is a Rust rewrite of the original adr-tools, attempting to balance backwards compatibilty with new features.

See the Resources section for more information about ADRs in general.

Configuration

Commands

adrs is a command line tool for creating and managing Architectural Decision Records based on the original adr-tools.

adrs supports the following list of commands:

  init      Initializes the directory of Architecture Decision Records
  new       Create a new, numbered Architectural Decision Record
  edit      Edit an existing Architectural Decision Record
  link      Link Architectural Decision Records
  list      List Architectural Decision Records
  config    Show the current configuration
  generate  Generates summary documentation about the Architectural Decision Records
  help      Print this message or the help of the given subcommand(s)

init

Overview

The init command initializes a new ADR directory, using doc/adr by default. An alternate directory can optionally be supplied to the command to store ADRs in a different location. init will also create the .adr-dir file to store the directory location so that other commands can find the top level directory.

init creates an initial ADR for you as well, noting the decision you've made to document your Architectural Decisions using ADRs. Good job by you.

Help

Initializes the directory of Architecture Decision Records

Usage: adrs init [DIRECTORY]

Arguments:
  [DIRECTORY]  Directory to initialize [default: doc/adr]

Options:
  -h, --help     Print help
  -V, --version  Print version

Examples

# use the default location
# an initial ADR will be created in doc/adr/0001-record-architecture-decisions.md
adrs init

# put your ADRs somewhere else
# creates some/other/place/0001-record-architecture-decisions.md
adrs init some/other/place

Issues

See the cmd-init label for command specific issues.

new

Overview

new creates a new ADR, optionally linking it to or superceding a previous ADR. A single call can link and/or supercede multiple previous ADRs.

Help

Create a new, numbered Architectural Decision Record

Usage: adrs new [OPTIONS] <TITLE>...

Arguments:
  <TITLE>...  Title of the new Architectural Decision Record

Options:
  -s, --superseded <SUPERSEDED>  A reference to a previous decision to supersede with this new one
  -l, --link <LINK>              Link the new Architectural Decision to a previous Architectural Decision Record
  -T, --template <TEMPLATE>      Use a custom template when generating the new Architectural Decision Record. Relative paths are resolved with respect to the directory specified in `.adr-dir` [env: ADRS_TEMPLATE_DIR=] [default: templates/template.md]
  -h, --help                     Print help
  -V, --version                  Print version

Examples

# create a new ADR
adrs new My New Decision

# create a new ADR that supercedes a previous ADR
adrs new -s 2 This is a new idea

# create a new ADR that links to a previous ADR
adrs new -l "2:Amends:Amended by" This is a better idea

# use an alternate template
# the template is resolved relative to the directory specified in `.adr-dir`
adrs new -T templates/alternate.md This is a different idea

Issues

See the cmd-new label for command specific issues.

edit

Overview

edit opens an ADR in your VISUAL or EDITOR that matches the given NAME argument.

Help

Edit an existing Architectural Decision Record

Usage: adrs edit <NAME>

Arguments:
  <NAME>  The number of the ADR to edit

Options:
  -h, --help     Print help
  -V, --version  Print version

Examples

# find and edit the first ADR
adrs edit 1  # looks for 0001-...
# find and edit the first ADR with the string "data" in the filename
adrs edit data

Issues

See the cmd-edit label for command specific issues.

link

Overview

The link command links together the SOURCE and TARGET ADRs.

Help

Link Architectural Decision Records

Usage: adrs link <SOURCE> <LINK> <TARGET> <REVERSE_LINK>

Arguments:
  <SOURCE>        The source Architectural Decision Record number or file name match
  <LINK>          Description of the link to create in the source Architectural Decision Record
  <TARGET>        The target Architectural Decision Record number or file name match
  <REVERSE_LINK>  Description of the link to create in the target Architectural Decision Record

Options:
  -h, --help     Print help
  -V, --version  Print version

Examples

# start a new ADR directory
adr init
# create a new ADR
adrs new Do something new
# create another new ADR
adrs new Do something else
# we have three ADRs
ls doc/adr/
0001-record-architecture-decisions.md
0002-do-something-new.md
0003-do-something-else.md
# link the third to the second with an "Amends" link
adrs link 3 Amends 2 "Amended by"

Now the status in 0003-do-something-else.md will be:

## Status

Accepted

Amends [2. Do something new](0002-do-something-new.md)

## Status

Accepted

Amended by [3. Do something else](0003-do-something-else.md)

Issues

See the cmd-link label for command specific issues.

list

Overview

list lists the current ADRs found in the configured (or default) directory.

Help

List Architectural Decision Records

Usage: adrs list

Options:
  -h, --help     Print help
  -V, --version  Print version

Examples

adrs list
0001-record-architecture-decisions.md
0002-do-something-new.md
0003-do-something-else.md

Issues

See the cmd-list label for command specific issues.

config

Overview

config shows the current configuration.

Help

Show the current configuration

Usage: adrs config

Options:
  -h, --help     Print help
  -V, --version  Print version

Examples

adrs config

Issues

See the cmd-config label for command specific issues.

generate

Overview

The generate command fronts three options for generating output for use with other tools.

• toc - generate a Markdown table of contents
• graph - generate a Graphviz representation of your ADRs
• book - generate a basic mdBook representation of your ADRs

Help

Generates summary documentation about the Architectural Decision Records

Usage: adrs generate <COMMAND>

Commands:
  toc    Generate a table of contents
  graph  Generate a graph of the ADRs
  book   Generate a book of the ADRs
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Examples

ToC

# Generate a Markdown Table of Contents for the local ADRs
adrs generate toc

Outputs the following on stdout:

# Architecture Decision Records

* [1. Record architecture decisions](0001-record-architecture-decisions.md)
* [2. Rewrite it in Rust](0002-rewrite-it-in-rust.md)
* [3. Use mdBook for documentation](0003-use-mdbook-for-documentation.md)

Graph

# Generate a Graphviz file graphing the ADRs and their relationships.
adrs generate graph

digraph {
  node [shape=plaintext]
  subgraph {
        _1 [label="1. Record architecture decisions"; URL="0001-record-architecture-decisions.html"];
        _2 [label="2. Rewrite it in Rust"; URL="0002-rewrite-it-in-rust.html"];
        _1 -> _2 [style="dotted", weight=1];
        _3 [label="3. Use mdBook for documentation"; URL="0003-use-mdbook-for-documentation.html"];
        _2 -> _3 [style="dotted", weight=1];
  }
}

Book

Generate a book of the ADRs

Usage: adrs generate book [OPTIONS]

Options:
  -p, --path <PATH>                Target path for the book directory [default: book]
  -o, --overwrite                  Overwrite existing directory
  -t, --title <TITLE>              Title of the book [default: "Architecture Decision Records"]
  -d, --description <DESCRIPTION>  Description of the book [default: "A collection of architecture decision records"]
  -a, --author <AUTHOR>            Author of the book
  -h, --help                       Print help
  -V, --version                    Print version

# Generate a basic mdBook based project for the current ADRs
adrs generate book

The book directory now contains a basic mdbook with:

• `book.toml' - the book's configuration
• src/SUMMARY.md - a Markdown file describing the structure of the book
• your ADR files - copied into the book and referenced by the SUMMARY.md

Get started by running mdbook serve in your book directory. See mdBook for more information.

Note that the command is currently pretty destructive, but requires the -o/--overwrite flag to work on an existing directory.

Issues

See the cmd-generate label for command specific issues.

Resources

• Architectural Decision Records https://adr.github.io
• adr-tools https://github.com/npryce/adr-tools
• When Should I Write an Architecture Decision Record https://engineering.atspotify.com/2020/04/when-should-i-write-an-architecture-decision-record
• ADR Process https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html#contents

Contributing

Help out however you can. See issues for ideas.

Guidelines

Compatibility

For now, keep additions compatible with the original adr-tools. New features can be added, however, as long as they don't break existing functionality. In the future, the tool may add incompatible features, but that will be a major version bump.

Testing

Please write new and/or update current tests as appropriate. See the current test suite for examples.

Documentation

All new or augmented features should have documentation.

Project ADRs

• 1. Record architecture decisions
  • Status
  • Context
  • Decision
  • Consequences
• 2. Rewrite it in Rust
  • Status
  • Context
  • Decision
  • Consequences
• 3. Use mdBook for documentation
  • Status
  • Context
  • Decision
  • Consequences

1. Record architecture decisions

Date: 2024-03-04

Status

Accepted

Context

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

Decision

We will use Architecture Decision Records, as described by Michael Nygard.

Consequences

See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's adr-tools.

2. Rewrite it in Rust

Date: 2024-03-04

Status

Accepted

Context

There are a bunch of rewrites already. Some of them look to be incomplete and/or abandoned. This implementation should be at least both feature equivalent to the current tools, compatible (or optionally compatible for backwards, uh, compatibility), and extensible with new features that make the tool even more useful.

Decision

Rewrite the original adr-tools in Rust.

Consequences

A blazingly fast Architectural Decision Record command line tool for the entire world to enjoy.

3. Use mdBook for documentation

Date: 2024-03-06

Status

Accepted

Context

A solid documentation site is the backbone of any good software project. While the tool should have decent built in docs, the doc site can contain a lot more information, as well as general information about the project.

Decision

adrs will have an mdBook based documentation site.

Consequences

Docs will be easier to navigate, search, and keep up to date.

License

See LICENSE-MIT or LICENSE-APACHE.