Command line tool for managing Architecture Decision Records
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.vscode
doc
src
.gitignore
LICENSE
README.md
conf.js
gendoc.bat
pack.bat
package.json

README.md

ADR Flow Tools

Code Climate contributions welcome

This project aims to provide a command line tool to work with Architecture Decision Records (ADRs).

This grew out of my need to have this kind of tool when working in a Windows OS.
The only option I found was the ADR tools project, which didn't work as easily in Windows. Still, it inspired this project.

This project is implemented as a series of Node.js scripts, with the relevant packages to support different functionality. It is packaged as a single binary using pkg. Using pkg allows us also to package this as an executable for other platforms.

As a tool, the ADR flow is implemented with a simple command line interface (CLI). This is intended to offer both a simple operation, and thus flexibility.
It is also intended to be used in conjunction with other command line tools. For example, some command outputs can be pipelined to other programs.

Usage

The tool is a simple command line, used to make the job of manipulating and exploring ADRs more easy.
It is however intended to be used directly with the ADR files on the file system. The idea being that these files are present right next to the source code, managed in source control, etc.

At any point, you can invoke the tool with the help switch to list available commands:

adr --help

You can also list help for a specific command, e.g.

adr link -h

which will show a description of the link command.

Initializing ADR Management

Given that you have the executable file, navigate to your project's root and initialize the ADR handling for this project:

adr init

This will create a default directory under your project root (doc/adr) which will contain the ADR files.
You can also specify a different directory as part of the command.

Configuration

The init command creates a .adr file in the ADR directory. Don't move or rename this file.
This file also contains configuration for the tool. At the moment it includes only the path to the editor that will be launched when writing an ADR.
It's a simple properties file with a single property: editor which should have the full path to the text editor of you liking.

Starting from version 0.3.0, you can also specify a file called local.adr right next to .adr which will be used to override the properties in .adr. This enables team to share configuration (through the source control system) in the .adr, while still allowing every developer to specify his own properties, e.g. different editor.
Note that it's advisable you don't commit the local.adr file, so it will not interefere with other team members' overriden properties. Add it to .gitignore/.svnignore or whatever other method your VCS uses.

Creating a New ADR

Creating a new ADR is done simply with the new command, followed by the title:

adr new Some Title

This will create a new ADR with the given title in it. It will assign a new available ID to the ADR.

Accepting an ADR

If an ADR is to be accepted, you can invoke the accept command:

adr accept 3

In this example, ADR #3 will be marked as accepted. This will add an Accepted entry in the ADR file, with the relevant date.

Listing ADRs

You can also list all the available ADRs:

adr list

This will list all the ADRs with their file names and IDs. You have the option to use the -b (--bare) option to output only the file names:

adr list -b

This might be useful for integration with other command line tools.

Exporting ADRs

You can also export ADRs to HTML with the export command:

adr export 3 adr3.html

This will create a file called adr3.html with the content converted to HTML (using marked).

Note that you can omit the output file argument, causing the output to spill out to standard output. This can be useful if you want to integrate with other command line tools.

Another option is to export all ADRs to a single file, with a table of contents.
To do that, simply specify * (asterisk) as the ID in the above command, e.g.:

adr export * all.html

Exporting Diagram

In addition to exporting the ADR content, one can also export a network figure (a graph) of all the ADRs and their connections, where applicable.
This allows the user to easily see relationships between ADRs.

Use the command:

adr diagram

to output such a diagram. The default output file name is diagram.html, but you have the option to specify another file name.

The output is an HTML, using vis.js do display the network graphic.

Customizations

It's possible to customize the behavior of the tool in certain ways (with probably more to come).

See the customizations page for details.

Contributions

Contributions are more than welcome of course.
Please make sure to follow conventions where applicable, and that all tests pass before submitting a pull request.

To execute tests, simply run npm test

Creating a Binary

Use pkg to create the executable. This will require node v6 and above.

pack.bat runs pkg that is globally installed, building a windows executable.

License

Copyright (c) 2017 Lior Schejter

MIT License.
See the LICENSE file for more details.