toko-tooling 0.45.0

Shared development tools, CI helpers and engineering rules for Toko Studios
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
# Changelog rules
<!-- Shared companions: rules/change-reporting.md rules/contributions.md rules/rust-workspaces.md -->

These rules are part of the mandatory [engineering baseline](../TOKO-TOOLING.md)
for repositories with changelogs. Read them before editing release notes.
Consumer overlays own audience, presentation and package-specific views within
this contract; the [release contract](../docs/releases/releases.md) owns release execution.

## Content and writing

- Keep legal and licensing changes out of changelogs, including root,
  package, release-group and archived or detailed changelogs. This includes
  licence adoption, terms, drafts, notices, contributor agreements, legal
  contribution eligibility, rights ownership and legal audits. Keep operative
  terms in the canonical root files and legal review records outside the
  repository under the baseline's
  [canonical-file policy]../TOKO-TOOLING.md#canonical-licence-and-contribution-policy.
  This exclusion overrides the
  usual meaningful-change, breaking-change and fixed-issue-link requirements;
  do not add a changelog entry merely to describe this policy or such cleanup.
  Do not add neutral adoption notices either. Previously published notices do
  not authorise new ones; this rule does not require rewriting published entries.
  It does not authorise removing legal notices, required provenance or Git history.
- Root `CHANGELOG.md` is the concise release ledger for a single release group.
  Independently versioned groups use the
  [group ledger and history rules]#release-group-changelogs-and-shared-history
  below. Lead with the outcome and practical effect for the repository's users,
  operators or developers. Use plain language and consolidate related changes
  into short bullets or summaries.
- Update the current draft by default when a meaningful behavior or maintained
  tooling batch is complete. Cover the coherent outcome, including relevant
  public APIs, commands, output fields, diagnostics and operational changes.
  Choose and maintain its next-version heading automatically under the rules
  below; do not wait for a separate changelog or version-number request.
  Another compatible implementation slice extends that draft.
  A pending note does not require immediate publication. Private-only group
  maintenance follows the
  [publication-impact decision]../docs/releases/releases.md#decide-whether-publication-is-needed;
  keep its note pending for the next actual release without bumping member
  versions or inventing a published entry.
- Omit formatting-only churn, incidental internal renames, routine test runs
  and governance-only edits unless they change a maintained surface or the
  maintainer explicitly requests a release note. Meaningful coverage or test
  tooling changes may be noted; a `Testing` section describes those changes,
  rather than listing validation commands.
- Root release entries use the [emoji section format]#root-emoji-sections
  established by IcyDB. Include only relevant categories; even a small entry
  has one section rather than an unlabelled bullet list. Repository titles,
  audience and detailed-note presentation remain consumer choices.
- Keep implementation inventories, internal paths, test names, footprint tables
  and long examples out of root summaries unless needed to explain a public
  contract or required action. Move useful detail to the linked minor-line notes.
  Neither root nor detailed notes should inventory moved, renamed or edited
  functions and types. Summarize refactoring by its outcome. Mention specific
  symbols only when needed to explain a meaningful API change or consumer action.
  The opt-in maintainer [symbol report]change-reporting.md#symbol-changes lists
  genuinely created and deleted declarations; keep that inventory out of release
  notes rather than relocating it into a detail file.
  Include a small representative example when it makes a newly supported
  command, query or configuration clearer; do not invent examples for cleanup.
- Describe supported behavior and measured effects accurately. Do not present
  planned work, a passing substitute test or an expected speed-up as shipped or
  qualified behavior. Routine validation results and readiness belong in the
  handoff or their existing evidence owner, rather than repeated release prose.

## Readable release layout

- Give each bullet one coherent outcome, normally in one or two short sentences.
  Split independent changes into separate bullets even when they belong to the
  same release or hard cut. Wrapping source lines does not split a rendered
  paragraph; review the Markdown as readers will see it.
- Group larger releases under the relevant emoji category headings below.
  Use short bold topic labels within bullets when they help readers
  distinguish areas, for example **Build inputs**, **Restore** or **Initialization**.
  Avoid deep nesting or creating a heading for every small change.
- Put required upgrade actions in a distinct, easy-to-find bullet or paragraph.
  Keep rebuild/reinstall requirements, retained-data implications and supported
  recovery boundaries explicit instead of burying them among implementation work.
- Keep issue links beside the outcome they explain. Do not append a detached
  `Owning changes` list or a comma-separated issue dump to an omnibus paragraph.
  Prefer one or two links per bullet; when more are needed, split by outcome or
  move the supporting detail into the minor-line notes, retaining every fixed
  issue's direct link in its owning release changelog. Keep titles concise and
  descriptive rather than copying a lengthy diagnostic into the link label.
- Separate unfinished follow-up from delivered changes. Mention it only when
  needed to explain a release limitation, with a clear label and its owning link.
- When the root entry becomes difficult to scan, retain the release outcome,
  breaking contract and required actions there, then link to grouped detailed
  notes. Do not compress a large release into one giant bullet to meet a summary
  convention, or remove meaningful issue coverage just to shorten the text.

## Root emoji sections

Keep release/version headings and dates unchanged, such as `## [0.26.20]` or
`## [0.26.19] - 2026-10-26`. Use emoji-labelled category headings beneath each
root release entry, following IcyDB's format:

| Category | Standard root heading |
| --- | --- |
| Breaking changes | `### โš ๏ธ Breaking` |
| Additions | `### โž• Added` |
| Changed behavior | `### ๐Ÿ”ง Changed` |
| Fixes | `### ๐Ÿฉน Fixed` |
| Removals | `### ๐Ÿ—‘๏ธ Removed` |
| Internal simplification | `### ๐Ÿงน Cleanup` |
| Test tooling or coverage | `### ๐Ÿงช Testing` |
| Documentation | `### ๐Ÿ“š Documentation` |
| Runnable CLI quick start | `### โ–ถ๏ธ Try it` |
| Migration instructions | `### ๐Ÿงญ Migration Notes` |
| Audit findings | `### ๐Ÿ“Š Audit` |
| Governance | `### ๐Ÿฅพ Governance` |
| Small or mixed release overview | `### ๐Ÿ“ Summary` |

For new entries, put breaking changes first when present. Omit empty or irrelevant
categories; one `๐Ÿ“ Summary` section is sufficient for a small patch. Product-specific
categories may keep a descriptive name with an appropriate emoji. Preserve an
existing minor-line index's version/link hierarchy and place category headings
at the next level beneath its release entry. This style does not require an
audit, line statistics, new release gate or a fixed roster of sections.

For releases adding or changing runnable CLI workflows, follow the baseline's
[root-changelog quick-start rule](../TOKO-TOOLING.md#cli-applications): put
`โ–ถ๏ธ Try it` immediately after any breaking notice, ahead of the other categories.
Keep the short setup and invocation commands in the root summary itself, including
for independently versioned groups whose detailed release ledger lives elsewhere.
This is a reader-facing exception to keeping command examples in detailed notes;
it does not move the authoritative group ledger or duplicate its full contents.

Apply this format to latest/current entries and future notes. Leave older
historical entries alone unless their reformatting is explicitly requested.
Presentation-only adoption need not regroup existing content; preserve release
versions, dates, ordering, bullet text, issue/detail links and code blocks.
Do not copy IcyDB's product-specific
audit or release policies into consumers. Keep explanatory formatting out of
release/deployment admission, as required by the finalization rules below.

## Issue links and compatibility

- **Every GitHub issue fixed by the work must have a direct clickable issue link
  in the owning release changelog, beside a concise description of the outcome.**
  For a workspace without independent release groups, use root `CHANGELOG.md`.
  For a workspace with independent release groups, use the owning group's
  `releases/<group>/CHANGELOG.md`; no duplicate issue entry is required in the
  workspace root index. A fix spanning groups belongs in each affected group's
  ledger with that group's outcome. Add links with the fix before handoff, even
  if issue closure or release is still pending. Links only in detailed notes,
  a PR, a commit or the final reply do not satisfy this requirement. Link the
  issue in its detailed entry too when present. Administrative closure without
  a fix is not a fixed issue and must not be presented as one.
- Every GitHub issue reference must include its number and title in the clickable
  link text, for example
  `[#123 โ€” Fix release retry failures](https://github.com/OWNER/REPO/issues/123)`.
  Use the actual issue title, or a concise, faithful shortening when it is long.
  Read the issue to verify its title and destination; never invent either.
  Do not use number-only links, bare URLs or lists of unexplained issue numbers,
  even when surrounding prose summarizes the batch. Each issue needs its own
  descriptive link so readers can identify it and click a useful target.
  Apply this to new and edited pending notes; preserve published history unless
  its correction is explicitly authorized.
- Mark breaking public API or semantic changes explicitly in the owning ledger's summary.
  State the affected contract and required consumer action, with fuller detail
  in the minor-line notes when needed. Include relevant API, CLI, response/error,
  wire/storage and execution-semantic changes; do not bury them under cleanup.
- State migration, regeneration, reinstall or reset implications accurately.
  A pre-1.0 hard cut does not waive retained-data or external-consumer obligations.
  Breaking public API or semantic changes require a minor release before 1.0.
  Report a conflicting selected patch target rather than silently renumbering it.

## Classify the released package's own impact

- Classify the actual contract delivered to that package's consumers. An upstream
  version number, a dependency's breaking release or the words "hard cut" do not
  automatically propagate a breaking bump to downstream packages. Inspect the
  complete pending batch and identify what an existing consumer must change.
- For a library, contributor-only CI, formatting, Git hooks, snapshot refreshes,
  development tool installation and local PATH changes are compatible when the
  published library contract is unchanged. Reinstalling contributor tools is not
  a library consumer migration. Before 1.0, select patch notes for such work;
  publication can wait for the next normal release rather than being required
  solely by the tooling update. Document setup actions under development/tooling
  notes without labelling the library release as breaking.
- Public APIs and exposed dependency types, runtime semantics, supported consumer
  build requirements, product CLI/output, protocols and stored formats still need
  compatibility assessment. For example, changing a dependency used in public
  signatures can break callers even when local source signatures look unchanged.
  Check the resolved dependency identity when consumers exchange its types:
  unchanged fields, arithmetic or wire/storage bytes do not by themselves make
  that upgrade compatible. Conversely, an internal dependency upgrade with no
  public contract impact does not require a downstream breaking release.
  A contributor toolchain change is distinct from raising the library's supported
  consumer MSRV or adding a required dependency to its published build.
- For a tooling product such as Toko Tooling, its supported installation paths
  and commands are the delivered interface. A change can therefore require a
  Toko Tooling minor release while its adoption needs only a consumer library
  patch. Product CLI users and deployment operators remain consumers of their
  respective published contracts; this is not a blanket tooling exemption.
- Select a release group's increment from the combined consumer impact of that
  group's packages. Preserve established groups until a boundary change is
  approved under the [workspace versioning rules]rust-workspaces.md#coordinated-versions-and-workspace-boundaries.
  Do not advance unrelated groups or manufacture breaking changes in sibling
  repositories to mirror an upstream bump.
- Correct an unpublished pending heading and matching detail notes if the only
  reason for a minor bump was internal tooling adoption. Check the entire batch
  for independent breaking changes first. Preserve published versions, tags and
  history, and any already-started release's reconciliation obligations. This
  clarification authorizes no manifest/version edit or release execution.

## Release-group changelogs and shared history

Independently versioned groups each own one canonical changelog at
`releases/<group>/CHANGELOG.md`, declared in `ci/cargo-release-groups.json`.
Crates released together share that ledger; do not require a separate changelog
per crate or privilege one group with the root ledger. Each ledger identifies
its group and covered packages. Root emoji sections, compatibility assessment
and automatic version selection apply to each group ledger. Single-group
repositories retain their existing root changelog and version convention.

For example, a workspace with Metrics and Logging uses:

```text
CHANGELOG.md                       # Group navigation index
releases/
  metrics/CHANGELOG.md              # Metrics group ledger
  logging/CHANGELOG.md              # Logging group ledger
  history.md                       # Earlier coordinated releases, if any
```

- Root `CHANGELOG.md` is an index linking every group ledger and, when present,
  `releases/history.md`. It contains no numbered release entries or aggregate
  workspace version. Fixed-issue links and outcomes belong in the owning group
  ledgers under the [issue-link rule]#issue-links-and-compatibility, not in a
  mandatory second issue index at the workspace root. This navigation does not
  duplicate release notes or create a shared release identity.
  Former crate-local ledgers may remain short navigation pointers when
  useful; update maintained links to the canonical path.
- Maintain at most one pending numbered entry per group that has changes, based
  on its own latest finalized release. Several groups may have pending entries
  in their separate ledgers. A release of one group does not finalize another
  group's notes. Toko Tooling or integration changes belong in the affected
  group ledgers only when they change those groups' maintained surfaces.
- Describe a change once in its owning ledger. When a dependent group requires
  adoption, its notes explain its own compatibility impact and link to the
  supplier's entry. Do not copy the supplier's implementation history or label
  every consumer adoption breaking solely because the supplier's minor changed.
- Preserve pre-split coordinated history once in `releases/history.md`, including
  versions, dates, headings, content and original release scope. Identify the last
  coordinated release. Group ledgers link back and identify where their own
  series begins; do not retroactively assign shared entries to individual groups.
  Omit the historical file when no coordinated history exists.
- During an explicitly requested adoption, move existing independent entries to
  their group ledgers and coordinated entries to the shared history without
  rewriting their release identity or prose. Preserve older group-specific history
  with its original scope. Update relative links and maintained references after
  moves; retain historical detail files and evidence. The historical ledger gets
  no new releases. A snapshot refresh alone does not migrate consumer ledgers.
- New detailed notes belong at `releases/<group>/<major>.<minor>.md`, avoiding
  collisions between equal version numbers in different groups. Existing linked
  historical detail paths may remain. Keep a single-group repository's existing
  paths. State the group alongside a version in cross-group reports or links.

Ledger organization does not authorize package moves, version resets, commits,
tags or publication. Preserve already-published identities and unfinished release
recovery. The [release mechanism](../docs/releases/releases.md#explicit-cargo-release-groups)
selects the group's own ledger; it does not finalize a shared historical file.

## Automatic next-version selection

- Keep one numbered, undated pending release at the top of the owning group's
  ledger (`CHANGELOG.md` for a single-group repository), using
  `## [X.Y.Z]` or `## [X.Y.Z] - Unreleased`. Automatically create or update it as
  part of completing meaningful work. Do not use an unnumbered `Unreleased` or
  `Draft` heading or a separate notes queue.
  Keep this pending entry undated until release preparation finalizes it.
- Derive the candidate from the latest finalized release and the complete pending
  batch since that release, not just the latest edit. Check the maintained
  release ledger, known tags/publication and canonical version source; an already
  prepared manifest or pending heading is not another released base to increment.
  Report a concrete identity conflict or missing initial version instead of
  inventing release history. Do not ask for routine version confirmation when
  the base and compatibility impact are clear.
- Before 1.0, choose the next patch for compatible fixes, additions and internal
  cleanup. Choose the next minor, resetting patch to zero, if any pending change
  breaks that package's public API, observable semantics, product CLI/output or
  wire/storage contracts. This includes a breaking hard cut, removal, or required
  product-consumer regeneration, reinstall or reset, assessed at the package's
  own boundary above. Contributor-only tooling reinstalls and internal hard cuts
  with no such consumer impact do not require a minor release. Moving to 1.0
  remains an explicit maintainer decision, rather than an automatic response to
  a pre-1.0 hard cut.
- From 1.0 onward, apply SemVer: compatible fixes use patch, compatible public
  additions use minor, and incompatible public changes use major. Honour an
  explicit maintainer-selected version when it satisfies the compatibility
  requirement; report an incompatible selected target instead of silently
  overriding it or describing a breaking release as compatible.
- Reuse the same pending entry until it is released. If later work makes an
  automatically selected patch breaking before 1.0, relabel that entire entry
  to the next minor from the same released base and carry all pending notes with
  it. Do not increment again for each slice, create multiple pending versions in
  one group, or rewrite a tagged/published entry. Keep every maintained changelog
  view and detail link aligned, including when a candidate changes minor line.
- In the handoff, state the selected next version and the compatibility reason,
  including the affected contract and required action for a breaking change.
- In Toko Tooling only, prepare root `Cargo.toml` package.version with the
  pending changelog during meaningful implementation.
  No separate version-edit request is needed. Use `## [X.Y.Z] - Unreleased` for
  this workflow so a prepared version is distinguishable from undated historical
  releases. Keep the file and heading equal; reuse that pair for further pending
  work, and promote both together if compatibility requires a larger bump. Do not
  bump on inspection-only tasks or create an empty release for each edit.
  Toko Tooling uses `make prepare-work [WORK_VERSION_KIND=patch|minor|major]`
  before adding the batch's notes, and `make check-version` rejects drift in CI.
  A version already present on `origin/main` is delivered for this workflow,
  even if its heading still says `Unreleased`; the next batch starts a new entry
  and preserves the pushed notes. The helper reads local remote-tracking refs
  without fetching. Honor the user's push confirmation and refresh stale remote
  evidence before preparation; a local commit or topic-branch push alone does
  not consume the version. Do not require a separate changelog/version request.
  Its release adapter derives the released base from that delivery evidence or
  the entry below a genuinely pending heading, then finalizes the prepared
  identity without a second bump.
  This is Toko Tooling's local workflow, not a consumer adoption requirement.
  Do not introduce `VERSION` or pending-file release mode in sibling workspaces.
- Outside Toko Tooling's own root package, this pending-version authority does
  not extend to Cargo/npm package versions, lockfiles or unrelated groups. It
  never authorizes commits, tags, pushes, publication or deployment.
  Do not introduce a root `VERSION` in a workspace with independent release groups
  or treat a file mirroring package metadata as an independent version owner.
  Requests such as "work on 0.4", "prepare 0.4" or "0.4 changelog" select the work,
  notes and, in Toko Tooling only, root package.version, not release execution.
  Commit and PR authority follows the [contribution rules]contributions.md.

For a latest finalized release of `0.14.7`:

| Complete pending batch | Top pending heading |
| --- | --- |
| Compatible fix or addition | `## [0.14.8]` |
| More compatible work before releasing that patch | Keep `## [0.14.8]` |
| Adopt a breaking Toko Tooling release; library consumer contract unchanged | Keep `## [0.14.8]`; describe contributor setup actions |
| Breaking hard cut, including one added to that pending patch | `## [0.15.0]`, carrying the complete pending batch |
| Compatible work added to that pending minor | Keep `## [0.15.0]` |

## Finalization and release history

- Keep the latest finalized release at the top until subsequent meaningful work
  needs its automatically numbered pending entry. Once a release tag exists or
  publication is reported, preserve that entry and collect later work under the
  next candidate derived from the new released base.
- During explicitly authorized release preparation, reconcile the numbered
  candidate with the selected release command, include work missing from the
  notes, and finalize it as `## [X.Y.Z] - YYYY-MM-DD` with the UTC release date.
  The standard release flow replaces ` - Unreleased` automatically before the
  release commit, tag and push. For a manual release, make that replacement
  before committing/tagging/pushing the release; never leave the marker on a
  published entry or change historical release dates afterward.
  Avoid duplicate entries for the same target; report a conflicting command
  instead of silently relabelling the prepared version.
- Changelog presentation, section position and pending labels must not block
  deployment. Release identity consistency belongs in release preparation.
  Report and repair missing notes when practical; explanatory prose is not an
  executable release or deployment guard.
- Preserve historical entries, dates, order and content. Do not silently rewrite
  published summaries to reflect today's implementation, delete history or
  reclassify imported undated releases as drafts. Historical notes are evidence,
  rather than authority for current supported contracts.
- Archive or correct historical notes only when explicitly authorized. Archiving
  retains all historical detail and leaves the version, date, concise summary and
  clickable detail link in the root ledger. Do not merge different minor lines
  into one detail file or discard content to shorten the root.
- Pending versions and date fields record note preparation; tags and registries
  establish their own publication state. Changelog text does not prove validation,
  publication, consumer adoption or deployment.

## Detailed notes when needed

- A small single-group repository may keep its notes entirely in root
  `CHANGELOG.md`. Add detailed notes when release volume or explanation makes the root hard to scan,
  or retain them when the repository already uses that structure.
- Use one `docs/changelog/<major>.<minor>.md` file for all patches in a minor
  line, rather than one file per patch. Use the automatically selected candidate's
  minor line for pending detail notes. If that candidate changes line, move only
  its unpublished notes to the matching file and update the root link; preserve
  finalized history in its original files. Independent groups use the
  group-specific paths described above.
- A root minor-line index uses a concise overview per patch. A small patch may
  need only one short bullet; a broad release needs separate outcome and upgrade
  bullets or grouped sections under the readable-layout rules above.
  Product-facing ledgers may retain linked release titles and brief prose.
  Keep minor lines and their patch summaries newest first; detailed patch sections
  follow the same order. Preserve existing historical ordering when adopting
  these rules rather than reorganizing published notes without authorization.
- Every patch in a minor-line index has a matching detail section. Keep root and
  detailed notes aligned on scope, patch identity and compatibility, with issue
  coverage at the owning entries as described above.
  Where both views date a patch, their dates must agree. Small detail sections
  may remain short. Extend both views for the same draft.
- Root entries must link to their detail files with clickable Markdown links.
  Resolve relative targets from the containing file: a root ledger uses, for
  example, `[Detailed notes](docs/changelog/0.33.md)`.
- Detailed notes explain meaningful implementation changes, operator-facing
  command/output surfaces, changed invariants and coverage, and required consumer
  actions. Link to evidence and operational procedures at their existing owners
  instead of copying command logs, release receipts or issue status.

Before handoff, check that the top pending version reflects the complete batch's
compatibility impact, the current notes cover the completed work, every issue
fixed in the batch has its direct link in the owning release changelog, issue and detail
links resolve, both views agree when present, and historical content is preserved.
This review does not require running a broad validation or release gate.