ADR Flow Tools
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.
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:
You can also list help for a specific command, e.g.
adr link -h
which will show a description of the
Initializing ADR Management
Given that you have the executable file, navigate to your project's root and initialize the ADR handling for this project:
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.
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
.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
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.
You can also list all the available ADRs:
This will list all the ADRs with their file names and IDs.
You have the option to use the
--bare) option to output only the file names:
adr list -b
This might be useful for integration with other command line tools.
You can also export ADRs to HTML with the
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
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:
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.
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 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
Creating a Binary
pkg to create the executable. This will require node v6 and above.
pkg that is globally installed, building a windows executable.
Copyright (c) 2017 Lior Schejter
See the LICENSE file for more details.