marouni / adr

A minimalist command line tool written in Go to work with Architecture Decision Records

ADR Go

A minimalist command line tool written in Go to work with Architecture Decision Records (ADRs).

Greatly inspired by the adr-tools with all of the added benefits of using the Go instead of Bash.

Quick start

Installing adr

Go to the releases page and grab one of the binaries that corresponds to your platform.

Alternatively, if you have a Go developement environment setup you can install it directly using :

go get github.com/marouni/adr && go install github.com/marouni/adr

Initializing adr

Before creating any new ADR you need to choose a folder that will host your ADRs and use the init sub-command to initialize the configuration :

adr init /home/user/my_adrs

Creating a new ADR

As simple as :

adr new my awesome proposition

this will create a new numbered ADR in your ADR folder : xxx-my-new-awesome-proposition.md. Next, just open the file in your preferred markdown editor and starting writing your ADR.

adr's Issues

Error installing Go adr

Unable to install this repo

C:\Users\xyz>go get github.com/marouni/adr
# github.com/marouni/adr
go\src\github.com\marouni\adr\commands.go:9:15: cannot use []cli.Command literal (type []cli.Command) as type []*cli.Command in assignment
go\src\github.com\marouni\adr\commands.go:19:33: cannot use c.Args() (type cli.Args) as type []string in argument to newAdr

I am using go version go1.13.8 windows/amd64

Feature Idea: support for multiple ADR locations

I was looking at adding support for multiple ADR locations for users who
need to support more than one ADR location. Would you be interested in me
opening PRs on this?

at this time I was thinking of extending the current configuration to support a slice or map of repositories. (probably a map as that provides a useful shortName lookup method)

Currently the config schema looks like this.

{
 "base_directory": "$ADRLOCATION",
 "current_id": 1
}

{
  "version": "v$n",
  "default": "Remembrancer",
  "repositories": {
    "Advocator": {
      "base_directory": "dir1"
    },
    "Deadline": {
      "base_directory": "dir1"
    },
    "Remembrancer": {
      "base_directory": "dir1"
    }
  }
}

New fields

• version: This tag would be used for future schema migrations.
• default: Instead of the root base_directory this value would allow the current behaviours to be replicated with an automated upgrade.
• repositories: A map of all repositories.
  • The short reference name for each repository
    • base_directory the local directory containing the repository

I would replace current_id with a directory scan as this is likely to work for most use cases.
when running the new version of the binary it should migrate the configuration to the newer version.

As part of this i would add an add command to add an already existing repository to your local config.

adr add /home/user/my_other_adrs

In the future I want to look at adding per repository templates and potentially config files.

Cannot get it to initialize. Using windows, git bash

Hi there!

1st try: init ./docs/decisions

$ adr init ./docs/decisions
Initializing ADR base at ./docs/decisions

mawi@LAPTOP MINGW64 /c/nkp temp/test3 (master)
$ ls
content.md

mawi@LAPTOP MINGW64 /c/nkp temp/test3 (master)
$ ls -a
./  ../  .adr-dir  .git/  content.md

mawi@LAPTOP MINGW64 /c/nkp temp/test3 (master)
$ cat .adr-dir
./docs/decisions

Hmm. Abort/Retry/Fail? Retry!

2nd try: /docs/decisions

mawi@LAPTOP MINGW64 /c/nkp temp/test3 (master)
$ rm .adr-dir

mawi@LAPTOP MINGW64 /c/nkp temp/test3 (master)
$ ls -a
./  ../  .git/  content.md

mawi@LAPTOP MINGW64 /c/nkp temp/test3 (master)
$ adr init /docs/decisions                                                                                            
Initializing ADR base at C:/Program Files/Git/docs/decisions

Oops.

Hmm. Abort/Retry/Fail? Retry!

3rd try: docs/decisions

mawi@LAPTOP MINGW64 /c/nkp temp/test3 (master)
$ adr init docs/decisions
Initializing ADR base at docs/decisions

mawi@LAPTOP MINGW64 /c/nkp temp/test3 (master)
$ ls
content.md

mawi@LAPTOP MINGW64 /c/nkp temp/test3 (master)
$ ls -a
./  ../  .git/  content.md

Hmm. Abort/Retry/Fail? Fail.

Any tips so I could get it to work?
Thanks!

BR! /m