jandev/adr-cli

A Windows equivalent of adr-tools (https://github.com/npryce/adr-tools). Original on https://github.com/GingerTommy/adr-cli, but appears to be abandonned.

ADR CLI tooling

A command-line tool for working with Architecture Decision Records (ADRs).

Installation

• Download the latest version of the adr-cli tool from the Releases page
  It's available for both Windows & Linux.

• Copy the executable to a location mentioned in the PATH of your system.

Usage

You can use this tool to create a directory for your ADR documents to be stored in and create new ADR files.
An index file will also be created on initial setup.

Init

adr-cli init

This will create the necessary folder (/docs/adr) from where you are running the command, including the initial document (0001-record-architecture-decisions.md) and the index file (0000-index.md).
Once created, it will try to open the initial file in your Markdown editor.

List

adr-cli init

Placeholder, does nothing yet.
This command is inherited from the previous implementation and can be deleted.

New

adr-cli new "New decision"

Will create a new ADR document with the mentioned title and a follow-up number.
The document will have the Proposed status.

The -s flag (supercedes) can be used like the following:

 ./adr-cli new "Superseded decision" -s "0003-another-decision.md"

This will result in an index like the following example:

# Index

| Number | Title | Superseded by |
| ------ | ----- | ------------- |
| 1 | [Record Architecture Decisions](./0001-record-architecture-decisions.md)| |
| 2 | [new-decision](./0002-new-decision.md)| |
| 3 | ~~[Another decision](./0003-another-decision.md)~~| [5 - superseded-decision](./0005-superseded-decision.md) |
| 4 | [Another decision](./0004-another-decision.md)| |
| 5 | [superseded-decision](./0005-superseded-decision.md)| |

Link

Placeholder, does nothing yet.
This command is inherited from the previous implementation and can be deleted.

Generate

Placeholder, does nothing yet.
This command is inherited from the previous implementation and can be deleted.

Publishing

If you don't want to use the Releases published in this repository, you can also publish them yourselves.

The FolderProfile in this solution is set up to do this.

If you're a fan of the dotnet CLI, publish using the following command:

dotnet publish -r win-x64 -c Release /p:PublishSingleFile=true /p:PublishTrimmed=true

Credits

This tool was originally started by GingerTommy. After having waited for a couple of months for my PR's to get approved, I've decided to create a new repository for the tool and use the original as a base.

adr-cli's Issues

Add index file

When initializing ADR, using the tool, create an index file (name suggestion 000 - Index.md).

This file will contain a list of all ADR documents, created by the tool.
The list will show the number and title of the document.

If a document has been superseded, the entry will be striked through and reference the superseded document. Example:

001 - Sample (superseded by: 003 - Superseded sample)

Create a release with version number

Whenever changes are pushed to main, make sure a new release is created with a corresponding version number.

Workflows are referencing vulnerable actions

Hello, there!

As part of the university research we are currently doing regarding the security of Github Actions, we noticed that one or many of the workflows that are part of this repository are referencing vulnerable versions of the third-party actions. As part of a disclosure process, we decided to open issues to notify GitHub Community.

Please note that there are could be some false positives in our methodology, thus not all of the open issues could be valid. If that is the case, please let us know, so that we can improve on our approach. You can contact me directly using an email: ikoishy [at] ncsu.edu

Thanks in advance

1. The workflow dotnet-core.yml is referencing action gittools/actions/gitversion/setup using references v0.9.7. However this reference is missing the commit 90150b4 which may contain fix to the vulnerability.
2. The workflow dotnet-core.yml is referencing action gittools/actions/gitversion/execute using references v0.9.7. However this reference is missing the commit 90150b4 which may contain fix to the vulnerability.
3. The workflow new-release.yml is referencing action gittools/actions/gitversion/setup using references v0.9.7. However this reference is missing the commit 90150b4 which may contain fix to the vulnerability.
4. The workflow new-release.yml is referencing action gittools/actions/gitversion/execute using references v0.9.7. However this reference is missing the commit 90150b4 which may contain fix to the vulnerability.

The vulnerability fix that is missing by actions' versions could be related to:
(1) CVE fix
(2) upgrade of vulnerable dependency
(3) fix to secret leak and others.
Please consider updating the reference to the action.

If you end up updating the reference, please let us know. We need the stats for the paper :-)

Add support for superseded documents

While there is some functionality for superseding documents already, it's not functional.

Functionality should be:

• Add the new ADR document
• Update the superseded document's status to superseded
• Reference the new ADR document in the old ADR document
• If #1 has been completed, update the Index file accordingly