docs: illustrate the two strategies against their tags #27

Merged

mikluko merged 1 commit from mikluko/octant/strategy-illustrations into main

2026-09-07 07:38:05 +00:00

mikluko commented

2026-09-07 07:33:13 +00:00

(Migrated from github.com)

The two strategy paragraphs stated what each does and left the reader to hold the contrast. These draw it.

What actually separates the strategies is the arity between the document and the tags, and where the date appears:

one entry, one tag

## [1.2.0] - 2026-08-01   ──▷   v1.2.0
## [1.3.0] - 2026-09-12   ──▷   v1.3.0

the entry is written complete, date and all, and merging cuts what it names

one entry, many tags

## [1.3.0]                ──▷   v1.3.0-rc.1     one per pull request
  no date, for as long    ──▷   v1.3.0-rc.2     into release/v1.3.0-rc
  as the branch lives     ──▷   v1.3.0-rc.3

## [1.3.0] - 2026-09-12   ──▷   v1.3.0          the merge dates that
                                                same entry, and that is
                                                the release

The parallel headings are the whole point: the same entry appears twice in the second block because it is the same entry, undated and then dated.

Plain text rather than a mermaid gitGraph. The repository already illustrates this way — CONTEXT.md's shape block, both example READMEs — and there is no mermaid anywhere in it. Branch topology is also not the interesting part; a gitGraph would draw the branches and hide the thing worth seeing. These render in a terminal, in less, and on any mirror.

80 columns, inside what the rest of the file uses. gen-readme leaves them alone — they sit outside the checks: markers, and the diff is 21 added lines and nothing else.

No changelog entry: two illustrations added to prose that already said this is below the bar the other entries are written to. [Unreleased] stays empty after 1.2.0.

The two strategy paragraphs stated what each does and left the reader to hold the contrast. These draw it. What actually separates the strategies is the **arity between the document and the tags**, and where the date appears: ``` one entry, one tag ## [1.2.0] - 2026-08-01 ──▷ v1.2.0 ## [1.3.0] - 2026-09-12 ──▷ v1.3.0 the entry is written complete, date and all, and merging cuts what it names ``` ``` one entry, many tags ## [1.3.0] ──▷ v1.3.0-rc.1 one per pull request no date, for as long ──▷ v1.3.0-rc.2 into release/v1.3.0-rc as the branch lives ──▷ v1.3.0-rc.3 ## [1.3.0] - 2026-09-12 ──▷ v1.3.0 the merge dates that same entry, and that is the release ``` The parallel headings are the whole point: the same entry appears twice in the second block because it *is* the same entry, undated and then dated. **Plain text rather than a mermaid `gitGraph`.** The repository already illustrates this way — `CONTEXT.md`'s shape block, both example READMEs — and there is no mermaid anywhere in it. Branch topology is also not the interesting part; a gitGraph would draw the branches and hide the thing worth seeing. These render in a terminal, in `less`, and on any mirror. 80 columns, inside what the rest of the file uses. `gen-readme` leaves them alone — they sit outside the `checks:` markers, and the diff is 21 added lines and nothing else. **No changelog entry**: two illustrations added to prose that already said this is below the bar the other entries are written to. `[Unreleased]` stays empty after 1.2.0.