ADR Process Tool

CLI to help with an ADR process lifecycle (proposal/acceptance/rejection/ deprecation/superseding) based on markdown files and git.

This tools is in pre-alpha state. Sphinx doc to be updated.

Features

pyadr

• pyadr init: initialise an ADR repository (corresponding BDD tests).
• pyadr new|propose Title of your ADR: propose a new ADR (corresponding BDD tests).
• pyadr accept [<file-path>]: accept a proposed ADR (corresponding BDD tests).
• pyadr reject [<file-path>]: reject a proposed ADR (see accept above for BDD tests).
• pyadr deprecate <file-path>: (not yet implemented) deprecate an ADR.
• pyadr supersede <superseded-file-path> <superseding-file-path>: (not yet implemented) supersede an ADR with another ADR.
• pyadr toc: generate a table of content (in format index.md) (corresponding BDD tests).
• pyadr helper: generate and syncs various useful things (corresponding BDD tests):
  • print title slug.
  • print title in lowercase.
  • synch filename with ADR title.
• pyadr check-adr-repo: performs sanity checks on the ADR repo (corresponding BDD tests).
• pyadr config [<setting>] [<value>]: configure a setting (corresponding BDD tests).

Help for all commands is available through pyadr help.

Help for individual commands is available through pyadr help <command>.

git adr

The git extension to pyadr does the following additional actions:

• git adr init (corresponding BDD tests):
  • initialise a git repository for the ADRs.
• git adr new|propose Title of your ADR (corresponding BDD tests):
  • create a new branch from main.
  • stage the new ADR in that branch.
• git adr accept [<file-path>] (corresponding BDD tests):
  • stage ADR to current branch.
  • optionally commit ADR.
  • optionally squash commits. (not yet implemented)
• git adr reject [<file-path>]: (corresponding BDD tests):
  • stage ADR to current branch.
  • optionally commit ADR.
  • optionally squash commits. (not yet implemented)
• git adr deprecate <file-path>: (not yet implemented)
  • create a new branch from main.
  • stage the deprecated ADR in that branch.
  • optionally commit.
  • optionally squash commits.
• git adr supersede <superseded-file-path> <superseding-file-path>: (not yet implemented)
  • create a new branch from main.
  • stage the superseded and superseding ADRs in that branch.
  • optionally commit both ADRs.
  • optionally squash commits.
• git adr commit <proposal|acceptance|rejection|deprecation|superseding> <file-path> [<superseding-file-path>]: (not yet implemented)
  • optionally stage ADR(s) to current branch.
  • commit ADR(s).
  • optionally squash commits.
• git adr helper: generate and syncs various useful things (corresponding BDD tests):
  • print title slug.
  • print title in lowercase.
  • synch filename with ADR title and staged renamed file.
  • print expected commit message for ADR.
  • print expected review request branch for ADR.
• git adr pre-merge-checks (corresponding BDD tests):
  • Performs sanity checks typically required on ADR files before merging a Pull Request.
• git adr config [<setting>] [<value>] (corresponding BDD tests one and two):
  • configure also settings specific to git adr.

Help for all commands is available through git adr help.

Help for individual commands is available through git adr help <command>.

Process Details

(Needs rewriting)

Once a proposed ADR placed in the docs/adr directory has been reviewed by peers, you can either action the decision to accept it (pyadr accept) or to reject it (pyadr reject), which will:

• Update the ADR content by:
  • Changing the ADR status (accepted or rejected)
  • Changing the ADR date to current date
• Change the ADR file name from XXXX-<whatever-is-here> to <next-available-id>-<adr-title-in-lowercase> (follows MADR-0005-format)

Various safety checks are performed before these actions take place. See BDD tests in the features directory.

Installation

To install ADR Process Tool, run:

$ pip install pyadr

Credits

This package was created with Cookiecutter and the opinionated-digital-center/python-library-project-generator project template.