Architectural Decision Record Automation

Use Case

We are electing to use Architecture Decision Records for documenting Orchestrator.

It would be good to have basic tooling to make it function properly.

Scope of Work

The upstream tools are low frequency and, in the case of the MADR extension which uses Markdown, the merge request to add upstream support was closed.

Contextual Information

Charts already uses a format very similar to what is specified and it works rather well.

Creating a very lightweight tool around the process will provide us with some benefits over time. The reasons for developing our own over the shell scripts:

  1. Low traffic updates on the repository
  2. Multiple decisions can supersede a previous decision. This should be linear replacement. C supersedes B which superceded A instead of C supersedes A and B supersedes A.
  3. Determine a way to manage decision relationships with structured data such as JSON to avoid string replacement inside markdown files

Acceptance Criteria

Mirror the functions from the primary tooling for adoption:

adr new My Decision Record    # creates a new record
adr new -s 1 My Replacement.  # -s means supersede decision number
adr generate graph            # generate a GraphViz graph .dot file
adr generate index            # generate the decision index