Canpolat.Talo 0.1.0-beta-6

talo

talo is a CLI tool to manage your ADRs, RFCs, design documents and more.

talo makes creation and management of your Architecture Decision Records, Requests for Comments and other design documents easy. You can define your own document types and use talo to manage them as well.

talo comes with features to list and export your documents (as HTML). This is what sets talo apart from similar tools.

If you are not familiar with ADRs or RFCs, this blog post offers a brief introduction: Documenting Design Decisions using RFCs and ADRs

Features

• Supports ADRs and RFCs out of the box. Comes with built-in templates so you can start writing immediately (you can also use your own templates, if you so desire).
• Template support: You can create and use your own templates for all record types (including the built-in ones).
• Supports custom document types: You are not limited to ADR and RFC. You can create and use your own document types and talo will manage them for you too.
• Support for updating record status: You can use the revise command to update the status of a document. This command will keep the version table in the record tidy. You can also use the link command to link documents to each other. See examples below.
• Listing: You can list all your records with their latest statuses.
• Exporting: You can export your records to HTML. talo will also create an index.html document that can be used to browse existing records. It will create links between records whenever necessary. See Export section below.

Installation

talo is released as a dotnet tool. If you already have dotnet, you can use the following command to install talo globally:

dotnet tool install --global Canpolat.Talo

Usage

Initialization

You can initialize whichever records types you are interested in. You don't have to initialize the types you will not use.

Initialize ADR

You can initialize your ADR workflow, by issuing the following command:

talo init adr

You can also use options to specify the directory location and the template path that will be used (if no template specified, talo will use the built-in template).

talo init adr --location docs/adr --template-path templates/adr.md

Initialize RFC

Initialization for RFC is the same as ADR. By replacing adr with rfc in the above section, you can initialize your RFC workflow:

talo init rfc

You can also check help:

talo init rfc --help

Bare initialization

If you don't want talo to initialize any of the built-in record types, you can use list without any sub-commands:

talo init

This will create a configuration file (.talo) at the current working directory. You can then configure your own record types and initialize them. See below for more information.

Listing your records

Listing ADRs

talo can list all your records (including your custom record types). To list all registered record types, issue the following command:

talo list

Or, you can list all your ADRs and RFCs by:

talo list adr

and

talo list rfc

Creating new records

To add new records, you can use the add command. For example:

talo add adr --title "Use event-based architecture" --status Accepted

If you want to apply a specific custom template to a single record, you can use the --from-template option.

talo add adr --title "Use GPL-3.0-or-later as license" --status Accepted --from-template templates/differentadr.md

Updating status of a record

The revise command can be used to update record status to any text.

talo revise adr --number 2 --status Obsolete

This will add status "Obsolete" as the last status of ADR number 2.

Linking documents to each other

There are two ways to link two documents to each other.

The first is when creating a new document. talo add has the --supersedes option to indicate that the new record is superseding an older one:

talo add adr --title "Use PostgresSQL for all database needs" --status Accepted --supersedes 3

The second method is more flexible as it allows you to specify the status text you want to use:

talo link adr --source 7 --source-status "Amends" --destination 6 --destination-status "Amended by"

After this command, record number 7 will get a new status Amends ADR0006 and record number will have Amended by ADR0007.

Export

You can use the export command to export your records to HTML. This can be useful if you want to deploy them to a web site so that a wider audience can access them.

talo export --help

By default, it will export all records. But you can specify types to limit the output:

talo export --types adr

This will create HTMl files at ./export/adr (relative to .talo file).

Note that talo will create an index.html file to make browsing easier. It will also create links between records whenever necessary (for example, a record will have a link to the record that supersedes it, and vice versa).

Configuration

The config command provides a means to configure the existing record types as well as create new ones.

If you want to change the directory or template location of an existing record type, you can do so by:

talo config adr --location docs/newlocation ----template-path templates/differentadr.md

This will update the configuration.

Create a custom record type

To create a new record type you need to provide a name (all-lowercase), a location and a template path. You can also specify a description. For example:

talo config add --name prd --location docs/prd --template-path templates/prd.md --description "Product Requirement Document"

After this, talo list command will list prd among the supported record types. And you can immediately start using this new command:

talo add prd --title "Shopping cart experience" --status "Under review"

And list it too:

talo list prd

You now have a new record type that has the same capabilities as the built-in types ADR and RFC.

Help

clear
talo --help

Samples

The samples directory contains some alternative templates that can be used instead of the built-in ones. The built-in templates are also included for convenience (if you want to tweak the built-in template, they are a good starting point).

Custom templates

Please pay attention the following points when creating a custom template. Once these are satisfied, talo will be happy to help.

Title line

talo uses the title line to populate lists and collect metadata. For that reason, the template needs to comply with the expected format. Make sure to use this as the first line in your template:

# {{SEQUENCE-NUMBER}}. {{TITLE}}

Status table

talo uses the status section in the document to read and write status information. Make sure to include it towards the top of your document:

## Status

| Status                   | Time               |
|--------------------------|--------------------|
| {{STATUS}}               | {{TIME}}           |

Demo

The video below demonstrates the power of talo. If you want to follow along, or reproduce the demo yourself, the source is at ./docs/demo.md

TODO: Insert GIF or link to demo

Attributions

• To convert markdown files to HTML, talo uses markdig with all advanced extensions activated.