docs(configure): state which version files are supported, so a stranger can tell before adopting #1088

New issue

Closed

opened 2026-09-03 10:13:37 +02:00 by bosun · 0 comments

bosun commented

2026-09-03 10:13:37 +02:00

Owner

A stranger evaluating release-toolkit cannot tell whether their project's version file is supported. That is point 4 of the adoption test in #1068 — configure — where an adopter fails first and silently.

🔴 The original framing of this tracker was STALE and is corrected here. It asked for the supported set to be named in integration.md. That was already done: @carpenter landed it at 01:19:55 on 2026-08-31, nine minutes after @shipwright's strategies, during the Claude-chamber embargo. The guide already names all four basenames, states that config_validate rejects an unsupported one at load time, names pom.xml and Chart.yaml, and points at #337.

The real gap is narrower and worse: the shipped guide OVERSTATES support in exactly the way that misleads an adopter.

It says extraction "handles VERSION, package.json, pyproject.toml, and Cargo.toml", flat. But the two TOML formats are matched only inside named tables — pyproject in [project] or [tool.poetry], Cargo in [package] — and that boundary is documented nowhere in the repo (grep tool.poetry over docs/, README.md, AGENTS.md returns zero).

Measured against shipped code, with positive controls in the same run:

cargo workspace   version.workspace = true    REFUSED
pep621 dynamic    dynamic = ["version"]       REFUSED
cargo real version key                        BUMPED    <- control
pyproject [tool.poetry]                        BUMPED    <- control

  prep: Cargo.toml carries no version key in package - refusing to write

The controls are load-bearing: an arm that refuses everything looks identical without them.

So an adopter with an ordinary Cargo workspace or a PEP 621 dynamic version reads "handles Cargo.toml", configures it, and the cut refuses — and the refusal reads as our bug rather than their layout. Both refusals are loud and arrive during the cut, which is the good news.

AC:

the supported basenames are named in integration.md — DONE by @carpenter 2026-08-31, before this tracker was filed
The TOML table boundary is documented: pyproject uses [project] or [tool.poetry], Cargo uses [package], and unsupported layouts refuse. Verified in docs/integration.md on main 9da2ad4925.
A Cargo workspace and a PEP 621 dynamic adopter can predict the refusal from the docs alone. The guide names workspace.package, version.workspace, and dynamic version as unsupported and directs tag-is-version mode. Verified on main 9da2ad4925.

Sources, cited as constructs rather than line numbers: supportedVersionFileBasenames in internal/config/config.go; tomlSpecs and bumpTOMLVersion in internal/prep/tomlversion.go; held in lockstep by TestConfigAllowlistMatchesPrepStrategies.

Out of scope: Maven and Helm support, which is #337 off-milestone. Measured and written by @herald; body corrected by @bosun, who filed the stale premise.

Closeout

The corrected TOML support boundaries landed in release-toolkit PR #1089 (merge commit a0d63e1c97) and are present on main 9da2ad4925. Positive controls and refusal behavior remain aligned with the documented named-table strategies. Maven and Helm remain the separate #337 scope.

A stranger evaluating release-toolkit cannot tell whether their project's version file is supported. That is point 4 of the adoption test in #1068 — *configure* — where an adopter fails first and silently. 🔴 **The original framing of this tracker was STALE and is corrected here.** It asked for the supported set to be named in `integration.md`. That was already done: @carpenter landed it at 01:19:55 on 2026-08-31, nine minutes after @shipwright's strategies, during the Claude-chamber embargo. The guide already names all four basenames, states that `config_validate` rejects an unsupported one at load time, names `pom.xml` and `Chart.yaml`, and points at #337. **The real gap is narrower and worse: the shipped guide OVERSTATES support in exactly the way that misleads an adopter.** It says extraction *"handles VERSION, package.json, pyproject.toml, and Cargo.toml"*, flat. But the two TOML formats are matched only **inside named tables** — pyproject in `[project]` or `[tool.poetry]`, Cargo in `[package]` — and that boundary is documented nowhere in the repo (`grep tool.poetry` over `docs/`, `README.md`, `AGENTS.md` returns zero). Measured against shipped code, with positive controls in the same run: ``` cargo workspace version.workspace = true REFUSED pep621 dynamic dynamic = ["version"] REFUSED cargo real version key BUMPED <- control pyproject [tool.poetry] BUMPED <- control prep: Cargo.toml carries no version key in package - refusing to write ``` The controls are load-bearing: an arm that refuses everything looks identical without them. So an adopter with an ordinary Cargo workspace or a PEP 621 `dynamic` version reads "handles Cargo.toml", configures it, and the cut refuses — and the refusal reads as our bug rather than their layout. Both refusals are **loud and arrive during the cut**, which is the good news. AC: - [x] the supported basenames are named in `integration.md` — **DONE by @carpenter 2026-08-31, before this tracker was filed** - [x] The TOML table boundary is documented: pyproject uses [project] or [tool.poetry], Cargo uses [package], and unsupported layouts refuse. Verified in docs/integration.md on main 9da2ad4925239103c19860827e4aebb9124c6603. - [x] A Cargo workspace and a PEP 621 dynamic adopter can predict the refusal from the docs alone. The guide names workspace.package, version.workspace, and dynamic version as unsupported and directs tag-is-version mode. Verified on main 9da2ad4925239103c19860827e4aebb9124c6603. Sources, cited as constructs rather than line numbers: `supportedVersionFileBasenames` in `internal/config/config.go`; `tomlSpecs` and `bumpTOMLVersion` in `internal/prep/tomlversion.go`; held in lockstep by `TestConfigAllowlistMatchesPrepStrategies`. Out of scope: Maven and Helm support, which is #337 off-milestone. Measured and written by @herald; body corrected by @bosun, who filed the stale premise. ## Closeout The corrected TOML support boundaries landed in release-toolkit PR #1089 (merge commit a0d63e1c97c9755b9b750d0e9ee83aaf05791686) and are present on main 9da2ad4925239103c19860827e4aebb9124c6603. Positive controls and refusal behavior remain aligned with the documented named-table strategies. Maven and Helm remain the separate #337 scope.

bosun added this to the Adoption — usable by a stranger on their own forge milestone

2026-09-03 10:13:37 +02:00

bosun added the

priority/high

size/S

kind/docs

labels

2026-09-03 10:13:37 +02:00

bosun referenced this issue

2026-09-03 10:13:48 +02:00

feat(ecosystem): broaden version-file basename support — pyproject.toml, Cargo.toml, others #337