1. Record architecture decisions

Date: 12/02/2016

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 in this article: http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions

Consequences

See Michael Nygard's article, linked above.

2. Implement as shell scripts

Date: 12/02/2016

Status

Accepted

Context

ADRs are plain text files stored in a subdirectory of the project.

The tool needs to create new files and apply small edits to the Status section of existing files.

Decision

The tool is implemented as shell scripts that use standard Unix tools -- grep, sed, awk, etc.

Consequences

The tool won't support Windows. Being plain text files, ADRs can be created by hand and edited in any text editor. This tool just makes the process more convenient.

Development will have to cope with differences between Unix variants, particularly Linux and MacOS X.

3. Single command with subcommands

Date: 12/02/2016

Status

Accepted

Context

The tool provides a number of related commands to create and manipulate architecture decision records.

How can the user find out about the commands that are available?

Decision

The tool defines a single command, called adr.

The first argument to adr (the subcommand) specifies the action to perform. Further arguments are interpreted by the subcommand.

Running adr without any arguments lists the available subcommands.

Subcommands are implemented as scripts in the same directory as the adr script. E.g. the subcommand new is implemented as the script adr-new, the subcommand help as the script adr-help and so on.

Helper scripts that are part of the implementation but not subcommands follow a different naming convention, so that subcommands can be listed by filtering and transforming script file names.

Consequences

Users can more easily explore the capabilities of the tool.

Users are already used to this style of command-line tool. For example, Git works this way.

Each subcommand can be implemented in the most appropriate language.

4. Markdown format

Date: 12/02/2016

Status

Accepted

Context

The decision records must be stored in a plain text format:

People will want to use some formatting: lists, code examples, and so on.

People will want to view the decision records in a more readable format than plain text, and maybe print them out.

Decision

Record architecture decisions in Markdown format.

Consequences

Decisions can be read in the terminal.

Decisions will be formatted nicely and hyperlinked by the browsers of project hosting sites like GitHub and Bitbucket.

Tools like Pandoc can be used to convert the decision records into HTML or PDF.

5. Help comments

Date: 13/02/2016

Status

Accepted

Context

The tool will have a help subcommand to provide documentation for users.

It's nice to have usage documentation in the script files themselves, in comments. When reading the code, that's the first place to look for information about how to run a script.

Decision

Write usage documentation in comments in the source file.

Distinguish between documentation comments and normal comments. Documentation comments have two hash characters at the start of the line.

The adr help command can parse comments out from the script using the standard Unix tools grep and cut.

Consequences

No need to maintain help text in a separate file.

Help text can easily be kept up to date as the script is edited.

There's no automated check that the help text is up to date. The tests do not work well as documentation for users, and the help text is not easily cross-checked against the code.

This won't work if any subcommands are not implemented as scripts that use '#' as a comment character.

6. Packaging and distribution in other version control repositories

Date: 16/02/2016

Status

Accepted

Context

Users want to install adr-tools with their preferred package manager. For example, Ubuntu users use apt, RedHat users use yum and Mac OS X users use Homebrew.

The developers of adr-tools don't know how, nor have permissions, to use all these packaging and distribution systems. Therefore packaging and distribution must be done by "downstream" parties.

The developers of the tool should not favour any one particular packaging and distribution solution.

Decision

The adr-tools project will not contain any packaging or distribution scripts and config.

Packaging and distribution will be managed by other projects in separate version control repositories.

Consequences

The git repo of this project will be simpler.

Eventually, users will not have to use Git to get the software.

We will have to tag releases in the adr-tools repository so that packaging projects know what can be published and how it should be identified.

We will document how users can install the software in this project's README file.

7. Invoke adr-config executable to get configuration

Date: 17/12/2016

Status

Accepted

Context

Packagers (e.g. Homebrew developers) want to configure adr-tools to match the conventions of their installation.

Currently, this is done by sourcing a file config.sh, which should sit beside the adr executable.

This name is too common.

The config.sh file is not executable, and so doesn't belong in a bin directory.

Decision

Replace config.sh with an executable, named adr-config that outputs configuration.

Each script in ADR Tools will eval the output of adr-config to configure itself.

Consequences

Configuration within ADR Tools is a little more complicated.

Packagers can write their own implementation of adr-config that outputs configuration that matches the platform's installation conventions, and deploy it next to the adr script.

To make development easier, the implementation of adr-config in the project's src/ directory will output configuration that lets the tool to run from the src/ directory without any installation step. (Packagers should not include this script in a deployable package.)

8. Use ISO 8601 Format for Dates

Date: 21/02/2017

Status

Accepted

Context

adr-tools seeks to communicate the history of architectural decisions of a project. An important component of the history is the time at which a decision was made.

To communicate effectively, adr-tools should present information as unambiguously as possible. That means that culture-neutral data formats should be preferred over culture-specific formats.

Existing adr-tools deployments format dates as dd/mm/yyyy by default. That formatting is common formatting in the United Kingdom (where the adr-tools project was originally written), but is easily confused with the mm/dd/yyyy format preferred in the United States.

The default date format may be overridden by setting ADR_DATE in config.sh.

Decision

adr-tools will use the ISO 8601 format for dates: yyyy-mm-dd

Consequences

Dates are displayed in a standard, culture-neutral format.

The UK-style and ISO 8601 formats can be distinguished by their separator character. The UK-style dates used a slash (/), while the ISO dates use a hyphen (-).

Prior to this decision, adr-tools was deployed using the UK format for dates. After adopting the ISO 8601 format, existing deployments of adr-tools must do one of the following: