npryce / adr-tools

Command-line tools for working with Architecture Decision Records

ADR Tools

A command-line tool for working with a log of Architecture Decision Records (ADRs).

Quick Start

Install ADR Tools.

Use the adr command to manage ADRs. Try running adr help.

ADRs are stored in a subdirectory of your project as Markdown files. The default directory is doc/adr, but you can specify the directory when you initialise the ADR log.

1. Create an ADR directory in the root of your project:

    adr init doc/architecture/decisions
   

   This will create a directory named doc/architecture/decisions containing the first ADR, which records that you are using ADRs to record architectural decisions and links to Michael Nygard's article on the subject.

2. Create Architecture Decision Records

    adr new Implement as Unix shell scripts
   

   This will create a new, numbered ADR file and open it in your editor of choice (as specified by the VISUAL or EDITOR environment variable).

   To create a new ADR that supercedes a previous one (ADR 9, for example), use the -s option.

    adr new -s 9 Use Rust for performance-critical functionality
   

   This will create a new ADR file that is flagged as superceding ADR 9, and changes the status of ADR 9 to indicate that it is superceded by the new ADR. It then opens the new ADR in your editor of choice.

3. For further information, use the built in help:

    adr help
   

See the tests for detailed examples.

The decisions for this tool are recorded as architecture decision records in the project repository.

adr-tools's Issues

Document the tool’s use of the pager

Env vars, default pager etc

This repos ADRs do not themselves use ISO date format

While browsing the ADR for ISO date format, I noticed the card itself wasn't using that format:

https://github.com/npryce/adr-tools/blob/master/doc/adr/0008-use-iso-8601-format-for-dates.md

# 8. Use ISO 8601 Format for Dates

Date: 21/02/2017

Have you run upgrade-repository on this repo?

Original blog post link nearly unvisitable in Chrome

Chrome's certificate warnings, and cross-site request blocking prevents many users from reading the original text.

Here is a link to the cached version, text-only.

Provide an AppImage

It'd be great if the app could be downloaded as a single binary, like the ones provided by an AppImage.

Overload template and direcotry file names with --arguments

This is a feature request.

Overload template file name and directory file name with arguments.

Use case would be to use adr command to manage other type of markdown files, e.g.:

alias prd='adr --template-file prd_template.md --dir-file .prd-dir'

This way we could create PRD files with the very same tool while steel being able to create ADR files:

adr new Use adr-toolset to manage PRDs as well
prd init doc/architecture/drivers/
prd new Needs to be testable
prd new Needs to be expandable
prd link 1 "Mentioned in" 2 "Can't break"
adr list # lists existing ADR documents
prd list # lists existing PRD documents

.adr-dir as the root of a tree

Providing a different perspective on the feature request in #51

We're looking into using this tool to manage a centralised adr repository for adrs spanning multiple repos and teams.
For organisational purposes we would like to reflect our internal team structure through the usage of (sub-)directories.
Would it be possible to have the adr new command accept a relative path to the root (where adr init was run/where .adr-dir points to).
I do recognise this would probably create problematic interactions with the link and supersede functionality but I'm open for a discussion on those potentially problematic areas.

Load template from a custom path

Would be nice, for reasons of language for example

`find` perm mode issue

I get the following issue when I call the adr command:

usage: /usr/bin/adr-help COMMAND [ARG] ...
COMMAND is on of:
find: invalid mode ‘+111’
Run 'adr help COMMAND' for help on a specific command.

Though unrelated in terms of hardware, I attempted the fix outlined here. And after making the following changes everything seems to work as it should.

diff --git a/src/_adr_commands b/src/_adr_commands
index f70dc86..df6c5d5 100755
--- a/src/_adr_commands
+++ b/src/_adr_commands
@@ -2,4 +2,4 @@
 set -e
 source "$(dirname $0)/config.sh"

-(cd "$adr_bin_dir" && find . -name 'adr-*' -perm +111) | cut -c 7-
+(cd "$adr_bin_dir" && find . -name 'adr-*' -perm /111) | cut -c 7-
diff --git a/src/adr-generate b/src/adr-generate
index cee7767..221897c 100755
--- a/src/adr-generate
+++ b/src/adr-generate
@@ -13,7 +13,7 @@ cmd=$1

 if [ -z $cmd ]
 then
-    (cd "$adr_bin_dir" && find . -name '_adr_generate_*' -perm +111) | cut -c 17-
+    (cd "$adr_bin_dir" && find . -name '_adr_generate_*' -perm /111) | cut -c 17-
 else
     "$adr_bin_dir/_adr_generate_$cmd" "${@:2}"
 fi

The output of find --version is the following:

find (GNU findutils) 4.6.0
Copyright (C) 2015 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Written by Eric B. Decker, James Youngman, and Kevin Dalley.
Features enabled: D_TYPE O_NOFOLLOW(enabled) LEAF_OPTIMISATION FTS(FTS_CWDFD) CBO(level=2) 

I am running Arch Linux x86_64 with kernel 4.5.4-1-ARCH.

I am not sure what source of this issue is but thought that it would be useful to have an issue and a solution for anyone else that comes by this problem.

Allow specification of adr-dir via env var

Having a file like .adr-dir at the root of a repo is somewhat of a thorn in the eye of people trying to keep the root of their repo as clean/approachable as possible.

Instead of configuring adr-tools using files it would be nice if we could use an env var to specify the ADR dir. By allowing that users could easily wrap adr itself in scripts which configure it in whatever way desired.

Would you be open for a PR that enables setting the ADR dir via an env var?

• Name suggestion: $ADR_DIR
• IMHO it should have precedence over the .adr-dir file but not super important to our specific use.

Use ISO 8601 Date Format

I found this repository via a link from the latest ThoughtWorks tech radar. Congrats on the publicity--I hope you enjoy some internet popularity because of it.

I was a little confused by the format of dates in the generated markdown files. Being in the United States, I'm used to seeing mm/dd/yyyy instead of dd/mm/yyyy. When I first read 0001-record-architecture-decisions.md, I thought the file was dated in the future.

Since ADR is a communication tool, it should be as unambiguous as possible. With that goal in mind, I think it makes sense to follow the ISO 8601 recommendations for date formatting--yyyy-mm-dd.

I see that it's possible to override the default date format via config.sh, but I still think it makes sense for the tool's default to be the ISO standard--it would make the tool friendlier to adopt, and save new users some head-scratching.

Allow overwriting of default TOC title

Currently the Table of Contents title is hard coded. Being able to change this would be advantageous where others may want the project name instead, especially as this is always before the intro contents.

https://github.com/npryce/adr-tools/blob/master/src/_adr_generate_toc#L47

Overwriting with -t or a similar arg could be used to achieve this.

Asciidoc Support

Hi there,

I love this project and want to use it internally. We like to use adoc (asciidoctor) and judging from some time I spent reading the source code it seems pretty simple to support an alternative format. Would you be interested in accepting a PR that adds support for arbitrary extensions, so we (and others) can use the markup language we feel comfortable with?

How do I create my own personal default init 0001?

Hi @npryce , I discovered your adr-tools via ruthmalan. And now successfully using it in 3 existing projects and going on for more.

I like to ask if there's a way for me to change the default 0001 decision script without changing the code. Not looking to remove your existing content. but just to add 2 or 3 extra lines unique to my company under decision and context section.

Let me know roughly how and I be happy to try to make this my first contribution to your wonderful tool.

Thank you 🙏 with much ❤️ for your ADR tools 😄

doc/adr vs. docs/adr

GitHub pages allows for publishing websites on github. As source, they have following sources

• gh-pages branch, folder /
• master branch, folder /
• master branch, folder /docs. - https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch

Note the s in the folder name.

In the (unrelated) project Eclipse Winery, the homepage is rendered from docs/. The ADRs are placed into the folder docs/adr. As a consequence, the ADRs are browsable in the homepage: http://eclipse.github.io/winery/adr/

In case the ADRs resided in doc/adr, there would be two folders, docs/ for the whole homepage and doc/adr for all the ADRs.

Therefore, I propose to rename the folder doc to docs. I would submit a pull request, but seeing a nice test coverage (refs #30 (comment)), I would only start if this is a consensus to rename the directory.

Generate an index.md

I understand that adr generate toc outputs its content to stdout for deployment scriptability.
But on the other hand, I like adr-log's -i parameter which generates directly the index.md file.

I propose to create a new command: adr generate index which accepts the same parameters as adr generate toc.
This command would call _adr_generate_toc and _adr_dir to create an index.md directly in the adr directory.

For small projects, when you don't want to setup deployment scripts for your doc, I think it simplifies the process:

adr new ...
adr generate index
git commit

versus:

adr new ...
adr generate toc > docs/adr/index.md
git commit

Eventually, you can add adr generate index to a pre-commit hook ;)

If you are OK with this issue, I can work on a pull request.

Adr help should use the user's preferred pager

OS X Homebrew Formula

Something like this installs it

class AdrTools < Formula
  desc "A command-line tool for working with Architecture Decision Records (ADRs)."
  homepage "https://github.com/npryce/adr-tools"
  url "https://codeload.github.com/npryce/adr-tools/tar.gz/1.0.0"
  sha256 "ceeba995d2319ba2735dd3c613bf145070efb8984886887a9edde7d498354b4b"

  def install
    bin.install Dir["src/*"] - Dir["src/*.md"]
  end

  test do
    system "true"
  end
end

Brew command on INSTALL.md does not work

On the INSTALL.md, it states that this can be installed with brew install olleolleolle/adr-tools/adr_tools, but this throws the error:

Error: inreplace failed
src/adr-init:
  expected replacement of "/usr/local/Cellar/adr_tools/2.0.0/config.sh" with "/usr/local/Cellar/adr_tools/2.0.0/bin/config.sh"

I'm guessing this is due to config.sh being removed in 2.0.0. It might be worth removing the brew command, or linking to a working variant? I think there is a working tap by @olleolleolle https://github.com/olleolleolle/homebrew-adr-tools. I've not tried it though, so maybe it doesn't.

Report ADR history in iCalendar format

See https://en.m.wikipedia.org/wiki/ICalendar

This would allow project history to be visualised in calendar apps

Allow packaging and distribution projects to easily configure data and binary directories

See issue #1 for an example why this is needed.

Current thoughts:

Have a config.sh file that is sourced at the top of every script, and defines location of files.

E.g.:

#!/bin/bash
set -e
source $(dirname $0)/config.sh

...

And config.sh would define shell variables (not environment variables). The default would be:

adr_bin_dir="$(dirname $0)"
adr_template_dir="$adr_bin_dir"

Packaging scripts could replace the entire file. E.g.

adr_prefix=/usr/local
adr_bin_dir=$adr_prefix/bin
adr_template_dir=$adr_prefix/share/adr-tools/templates

Comments from packaging experts welcome.

CMDer support for adr-tools

Hi, I am unable to get adr-tools working with cmder on Windows 10. Is it supported?

Delete a decision

If I create a decision by mistake should I manually delete the decision document or there is a command for that?

Add option for having status values use shields.io

Github users have been conditioned to look for shields.io tags as a quick way to understand the state of a repo. It'd be great if the Status section that is generated could replace the STATUS with a shields.io image instead of using just plain text.

Examples:

For clarity I'm thinking of a command line switch:
adr --shields new URL Scheme
adr --shields new -s 1 Updated URL Scheme

Suggestion: adr-config could report absolute path

The output of adr-config could be more useful if the absolute path to the directory is known, especially when using its output from a different directory to the one adr-config was executing in.

However, it's not necessary or even desirable to use the physical structure (resolved symlinks). The following incantation will, on MacOS and various Linuxes (including BusyBox), emit the full path to the script's directory.

$(cd -L $(dirname $0) >/dev/null 2>&1 && pwd -L)

This would emit something like /home/nat/code/adr-tools/src rather than just . or ../adr-tools/src.

While not absolutely vital for the adr-config provided as a default for when executing from the source distribution, it is a good practice and might help binary package maintainers.

The consequence is if the output is used in anything that would traverse hosts, the absolute file path would probably be invalid (but that is the case for most .. paths anyway).

TOGAF 9.1 Architectural Principle format?

Generated table of contents is not sorted

Still maintained?

@npryce @npryce-springer are you still maintaining this tool? Do you want or need help with reviewing & merging pull requests?

I am noticing a steady influx of unaddressed PRs. I was packaging this script for NixOS. That made me curious whether there is enough momentum on this project to keep it well maintained.

Feature request: search parent directories for `.adr-dir`

In my company, ADRs live in architecture/.

I was in the architecture/ dir, and ran adr new ..., and was surprised to find that a architecture/doc/adr folder was created.

It'd be great if _adr_dir searched in parent directories to see if there was a .adr-dir, just as git searches parent directories for a .git.

Thanks for this great project, by the way! :)

Add decisions dir to TOC paths

I'd like to output the TOC to an MD file on root of project, but links to the MD files are made so that file would have to be in the decisions dir itself.

I.e.

* [1. Record architecture decisions](0001-record-architecture-decisions.md)

I'd like a flag in generate toc to generate links with the decisions dir added, or perhaps relative to the current folder, or as a string to prefix every path. Which (if any) do you prefer?

I.e.

* [1. Record architecture decisions](decisions/0001-record-architecture-decisions.md)

(and thanks for making the tool, it's fun and useful :)

adr init with alt directory doesn't work

I just tried using an alternative dir as suggested in the tests, however the dir was ignored, and the default used:

$ brew install olleolleolle/adr-tools/adr_tools
==> Installing adr_tools from olleolleolle/adr-tools
==> Downloading https://codeload.github.com/npryce/adr-tools/tar.gz/1.1.0
$ adr init alternative-dir
doc/adr/0001-record-architecture-decisions.md

Make the adr-config configurable, per user, per project.

##We are collaborating on several teams each with their own requirements for ADR specifications. We would like to use a .adr-config in the current directory, then ~/.adr-config and then use the system wide package adr in $(directory $0)/adr-config

How to install ADR tools in windows system?

Hi,
I am not finding any userful resource to setup ADR tools on windows system. Can you please point me to the right documentation..

Thanks,
Hari

Central store to aggregate ADRs from multiple projects

In a larger organization it could be useful to collect ADR files from different projects (maintained by different teams) and 'publish' them on some central WEB portal for visibility.
Did anyone thought / implemented something like that?

add 'install' option to Makefile

Would it be possible to package up this set of tools such that make install will work?

adr init with spaces in "alternate-dir" path fails

Doing an adr init with a path that has spaces in it fails; then uses the default.

:~$ mkdir path\ with\ spaces
:~$ cd path\ with\ spaces/
:~/path with spaces$ adr init
/usr/local/Cellar/adr-tools/3.0.0/bin/_adr_dir: line 16: [: too many arguments
doc/adr/0001-record-architecture-decisions.md

Configuration makes homebrew difficult

Refer to Homebrew/homebrew-core#3947 for details.

Create new ADRs in the "Proposed" state by default

Currently a new ADR is created in the Accepted state by default.

I suggest it is better to create new ADRs in the Proposed state. ADRs are meant to be discussed and agreed within a team. When team members are not all colocated, discussion can occur around or within the ADR document itself, until the team agree that the ADR is ready to be marked as Accepted.

This would also encourage teams to record proposed architecture decisions that are discussed and then rejected, along with the reasons for rejection.

Document the Markdown format conventions & restrictions used by the tools

add configuration for Date format

Hello

I wonder if it would be possible to configure the date format ? I would like use a dd/MMM/yyyy format, which will be less confusing for my team.

I see there is a sort of config file, could we add the date format here ? Does it make sense ?

I can work on the code, but I would need some guidances to know if it's make sense and if I pinpoint the impacted file(s) :)

test installer for the asdf-vm version manager

I created a adr-tools plugin for asdf-vm and have an opened PR to register it.

asdf gives osx and linux users (ci jobs) a 'universal' path to managing tool versions. Anyone care to test it out? especially osx users? Here is a quicky, but read the asdf README.md too. Once the asdf-plugin PR is approved, the git urls will not be needed:

$ asdf plugin-add adr-tools https://gitlab.com/td7x/asdf/adr-tools
$ asdf list-all adr-tools
$ asdf install adr-tools 2.0.1
$ asdf (global | local) adr-tools 2.0.1
$ adr

It would be nice to have others try it out and make sure it works beyond my pipeline & computer.

Deprecated flag used with "find" command

After installing adr to /opt/adr-tools/1.2.0/ on Ubuntu 16.04 and running adr, the following error is shown:

usage: /opt/adr-tools/1.2.0/adr-help COMMAND [ARG] ...
COMMAND is one of: 
find: invalid mode ‘+111’
Run 'adr help COMMAND' for help on a specific command.

After running sudo sed -i 's@-perm +111@-perm /111@' /opt/adr-tools/1.2.0/*, running adr produces:

usage: /opt/adr-tools/1.2.0/adr-help COMMAND [ARG] ...
COMMAND is one of: 
  init
  new
  generate
  help
  list
Run 'adr help COMMAND' for help on a specific command.

http://man7.org/linux/man-pages/man1/find.1.html sayeth:

The syntax -perm +MODE was removed in findutils-4.5.12, in favour of
       -perm /MODE.  The +MODE syntax had been deprecated since
       findutils-4.2.21 which was released in 2005.

On my system, find --version gives find (GNU findutils) 4.7.0-git

executable bit on adr-config?

I hastily made a PR to the homebrew package, without testing. Silly me.

On closer inspection, it looks like adr-config needs to be executable.

Otherwise I get:

> adr upgrade-repository
/opt/boxen/homebrew/bin/adr: line 3: /opt/boxen/homebrew/bin/adr-config: Permission denied

I would make a PR, but I've broken enough things for one day. Will test again tomorrow.

mulitple folders in .adr-dir

Hi I am managing a folder structure as belows:

doc > architecture > front-end
doc > architecture > back-end

Every time I use adr new I had to overwrite .adr-dir file.

Is there a way to accommodate multiple folder structure.

Create an `adr dir` command

... to report the location of the ADR directory relative to the current working directory.

Useful for writing scripts that manipulate ADRs, Makefiles for publishing ADRs, etc.

Content licensing?

I am somewhat confused by this clause in the LICENSE.txt

Content that this tool adds to your project is under the
Creative Commons Attribution 4.0 (CC BY 4.0) licence.

Does this only apply to the automatically generated phrasing of the ADRs? It surely does not apply to the content that you fill in, does it? It may be helpful to clarify this.

adr-tools doesn't work correctly in git bash because `more` is missing

The linux toolset included with git bash is missing more which means that adr help (f.e.) doesn't work.
git bash does have less which works just as well, so my initial workaround was to copy less.exe to more.exe in the git bash usr/bin/ folder.

Is there a technical reason why adr-tools uses more rather than less? Could it be changed without breaking other platforms?

I can submit a PR with an updated INSTALL.md which includes a note about copying less to more, or I can submit a PR with the shell script change to use less instead of more.

Bash autocompletion

Support autocompletion of adr sub-commands and options in the Bash shell.

Support for i18n

Hi !

I definitely love this !

But would it be possible to add some i18n support so that

• the adr generate toc command outputs a locale aware title
• the adr init [...] creates a localized version of the first decision

Thanks in advance !

Improve documentation on TOC and Generate options

I've been assessing the tool (great work!) and found that it took me a while to discover the format of the generate graph option. I had to run adr help generate graph in order to find it, but took me a while to realise that there was help for generate graph and generate toc independently.

Maybe split the actions into adr graph and adr toc?

Change in 2.2.0 to use of "-more" in help does not work in Git Bash

ad-help changed in 2.2.0 to use PAGER:-more which results in more command not available error when using Git Bash on Windows. Prior to this it did work.