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:
This works well with version control systems.
It allows the tool to modify the status of records and insert hyperlinks when one decision supercedes another.
Decisions can be read in the terminal, IDE, version control browser, etc.
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:
- Accept mixed formatting of dates within their documentation library.
- Update existing documents to use ISO 8601 dates by running
adr upgrade-repository