0003: Number records with inkan new

Context#

Records are numbered files, 0007-use-kafka.md, and the number is part of how people refer to them (PLATFORM-ADR-0007). Finding the next free number by hand means listing a folder and counting; two people doing that on the same day get a conflict. Each record also starts from the same skeleton, with today’s date and the author’s handle, which nobody wants to type again. log4brains and adr-tools both solved this with a new command, and users expect one.

Decision#

inkan new <type> <project> "<title>" creates the next numbered record of a type inside a project from a template. The number is one more than the highest number already in that folder. The file name is the number padded to four digits plus a slug of the title. The template comes from your templatesDir when it has a file for that type, otherwise from the package. If the project folder has no _project.yml yet, the command creates a minimal one so the project appears on the site with a name. An existing folder can be named by its slug: inkan new adr ops-plans "…" writes into Ops Plans/.

How to use it#

The command#

1
npx inkan new adr platform "Move the event bus to Kafka"
2
# Created decisions/platform/adr/0010-move-the-event-bus-to-kafka.md
3

4
npx inkan new rfc payments "Settle in async batches" --author jules

With the npm script that init adds: npm run new -- adr platform "Move the event bus to Kafka".

Numbering#

The command reads the folder <contentDir>/<project>/<type>/, takes the leading digits of every file name and adds one to the largest. An empty or new folder starts at 0001. Numbers are per project and per type, so sre/adr/0003 and sre/rfc/0003 are different records, and gaps are allowed: deleting 0005 does not renumber anything, and the next record after 0004 and 0009 is 0010. Numbers are padded to four digits.

The site derives the number from the file name the same way, so a record you create by hand with a correct name is indistinguishable from one created by the command. See Record type comes from the folder.

The slug#

The title is lowercased, accents are stripped (é to e, ł to l), every run of characters that is not a-z or 0-9 becomes one -, and leading or trailing hyphens are removed:

Templates and placeholders#

Templates are Markdown files named after the type: adr.md, rfc.md, postmortem.md. The package ships adr.md and rfc.md. Your own templates live in templatesDir (default templates/, relative to the config file); a file there with the same name replaces the built-in one, and types without a file fall back to the package’s. A type with no template at all gets a three-line front matter with title, date and authors.

Three placeholders are replaced everywhere in the template:

The built-in ADR template:

1
---
2
title: {{title}}
3
description: One sentence that says what was decided.
4
status: proposed
5
date: {{date}}
6
authors: [{{author}}]
7
deciders: []
8
tags: []
9
---
10

11
## Context
12

13
What is the problem and why does it need a decision now?
14

15
## Options considered
16

17
1. **Option A**: …
18
2. **Option B**: …
19

20
## Decision
21

22
What we will do.
23

24
## Consequences
25

26
What becomes easier or harder because of this decision.

The built-in RFC template starts with status: draft and has the sections Summary, Motivation, Proposal, Alternatives and Open questions. To use your own, copy a built-in file into templates/ and edit it:

1
templates/
2
  adr.md          replaces the built-in ADR template
3
  postmortem.md   template for a custom type from docTypes

Automatic _project.yml#

When <contentDir>/<project>/_project.yml does not exist, the command writes one before creating the record:

1
name: payments
2
description:
3
owners: []

It prints a reminder to fill in the details. The folder name is the id used in URLs; name is only the display name, so set it to Payments. See One folder per project and the fields in the front matter reference.

Author handles#

Without --author, the command looks the Git user up in _authors.yml: an entry whose email matches git config user.email, or whose handle, name, github or gitlab matches git config user.name, gives its handle, so Jane Doe <jane@example.com> becomes authors: [jane.doe]. Without a match the Git user name is written as it is, for example Jane Doe, and inkan check reports it as an unknown author; pass --author jane.doe or edit the line after creation. The RFC on filling date and authors from git discusses the same matching for date and authors at build time.

Custom fields that have a default are written into the new record’s front matter. See Custom metadata fields.

Consequences#

• The next number is always right for the folder you have checked out. Two branches that both add 0010 still conflict at merge time; the build does not notice, but inkan check reports the clash as a duplicate-number error, so the CI check from init catches it on the merged branch. See Check records in CI.
• Templates are plain Markdown with three placeholders. There is no templating language, no conditionals and no per-project template.
• The command needs the config to know contentDir, templatesDir and docTypes, so it must run in the folder with inkan.config.* or with --root.
• The slug only keeps ASCII letters and digits. Titles in scripts without a Latin transliteration produce very short slugs; rename the file if you need to, the number is what matters.
• Nothing is renumbered or renamed afterwards. Changing a title later leaves the file name as it was, which keeps links stable.