docs(modules): the module release version is derived, not declared #171

wtclaude · 2026-08-19T18:03:29Z

wtclaude commented

2026-08-19 18:03:29 +00:00

What & why

Reverses settled decision 19 and amends §2.7.1's "Releases: the version is declared, not computed".

The argument for a declared version is still true, and the trade it made was still wrong — worth separating, because the reason generalises: its cost is paid on every release, and the drift it prevents is something review catches anyway.

Measured, not argued. Between the phase 3 release on 2026-08-12 and today, v0.3.0 was the only release Module-uo ever cut, while the nine Teams phases and the cutover landed on its main. None of them touched module.json's version line, so none of them produced a bundle — and shipping the week's work meant first writing, reviewing and merging a pull request whose entire content was a number.

What the amendment records:

the engine that replaced it (link's — feat!/BREAKING CHANGE → major, feat: → minor, fix:/perf: → patch, nothing → no release);
the tag is the number that ships, written into the module.json inside the bundle at assembly time, with an assertion that the rewrite happened;
the declaration kept as a floor, so the old model is demoted to the special case it always was rather than deleted;
the workflow_dispatch backdoor, and why the larger of log-and-input wins;
the property that survives untouched: the workflow still never writes to a branch, which was always the half that mattered under branch protection.

The original subsection is left standing with the amendment beneath it, not rewritten — decision 33's rule for a record that has been overtaken. Its heading gains "— reversed 2026-08-19" so a reader skimming headings is not misled.

How it was tested

Markdown only. Checked that no other document states the old rule — docs/modules/uo/README.md describes install mechanics, which do not change, and MODULE_API.md says nothing about release cadence. No links added or moved.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

No AI tools were used to produce this contribution.
AI tools were used. Tool(s): Claude Code (Opus 5). I have reviewed and understand
every change, and take responsibility for it. AI-authored commits are
marked with a Co-Authored-By / Assisted-By trailer.

License

I agree that my contribution is licensed under this project's license
(GNU GPL v3.0 or later), and I have the right to contribute it.

The code half is RunicGateway/Module-uo#17; the kit half is RunicGateway/Integration-kit#8.

## What & why Reverses **settled decision 19** and amends §2.7.1's *"Releases: the version is declared, not computed"*. The argument for a declared version is still true, and the trade it made was still wrong — worth separating, because the reason generalises: **its cost is paid on every release, and the drift it prevents is something review catches anyway.** Measured, not argued. Between the phase 3 release on **2026-08-12** and today, **`v0.3.0` was the only release `Module-uo` ever cut**, while the nine Teams phases and the cutover landed on its `main`. None of them touched `module.json`'s version line, so none of them produced a bundle — and shipping the week's work meant first writing, reviewing and merging a pull request whose entire content was a number. What the amendment records: - the engine that replaced it (`link`'s — `feat!`/`BREAKING CHANGE` → major, `feat:` → minor, `fix:`/`perf:` → patch, nothing → no release); - **the tag is the number that ships**, written into the `module.json` inside the bundle at assembly time, with an assertion that the rewrite happened; - the declaration **kept as a floor**, so the old model is demoted to the special case it always was rather than deleted; - the `workflow_dispatch` backdoor, and why the **larger** of log-and-input wins; - the property that survives untouched: the workflow still never writes to a branch, which was always the half that mattered under branch protection. **The original subsection is left standing with the amendment beneath it**, not rewritten — decision 33's rule for a record that has been overtaken. Its heading gains *"— reversed 2026-08-19"* so a reader skimming headings is not misled. ## How it was tested Markdown only. Checked that no other document states the old rule — `docs/modules/uo/README.md` describes install mechanics, which do not change, and `MODULE_API.md` says nothing about release cadence. No links added or moved. ## Checklist - [x] I have read CONTRIBUTING.md. - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [ ] No AI tools were used to produce this contribution. - [x] AI tools were used. Tool(s): `Claude Code (Opus 5)`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` / `Assisted-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it. --- The code half is **RunicGateway/Module-uo#17**; the kit half is **RunicGateway/Integration-kit#8**.

wtclaude added 1 commit 2026-08-19 18:03:35 +00:00

docs(modules): the module release version is derived, not declared a605c03eae

Reverses settled decision 19. The argument for a declared version is still true
and the trade it made was still wrong, which is worth separating: its cost is
paid on every release, and the drift it prevents is something review catches
anyway. Between the phase 3 release on 2026-08-12 and today, v0.3.0 was the only
release Module-uo ever cut, while nine Teams phases and the cutover landed on its
`main` - none of them touching `module.json`'s version line, so none of them
producing a bundle.

Records what replaced it: `link`'s engine, the tag as the number that ships,
CI writing it into the bundle's `module.json`, the declaration demoted to a
floor, and the `workflow_dispatch` backdoor for a `module.json` change with no
releasable code behind it.

The original subsection is left standing with the amendment beneath it rather
than rewritten, as decision 33 asks of a record that has been overtaken.

Pairs with Module-uo's `.gitea/workflows/release.yml` and the same change to the
Integration kit's template.

Co-Authored-By: Claude <noreply@anthropic.com>

wtclaude referenced this pull request from RunicGateway/Integration-kit

2026-08-19 18:04:00 +00:00

docs(book): teach the derived release version, and move the template onto it #8

whitlocktech merged commit 8abce24700 into main

2026-08-19 18:07:20 +00:00

whitlocktech deleted branch docs/module-uo-release-cadence

2026-08-19 18:07:20 +00:00

whitlocktech referenced this issue from a commit

2026-08-19 18:07:21 +00:00

Merge pull request 'docs(modules): the module release version is derived, not declared' (#171) from docs/module-uo-release-cadence into main

Sign in to join this conversation.