Skip to content

docs(readme): stop restating crate versions in the README - #955

Merged
justin13888 merged 5 commits into
masterfrom
ci/release-pr-refresh-readme-versions
Oct 24, 2026
Merged

justin13888 merged 5 commits into
masterfrom
ci/release-pr-refresh-readme-versions

Conversation

@justin13888

@justin13888 justin13888 commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator

Release PR #820 fails Format & Metadata: check-readme-crates refutes the crates-table tokens for gamut-isobmff (v3 → 4.0.0), gamut-avif (v2 → 3.0.0) and gamut-exif (v2 → 3.0.0). The guard held each row's vN token and the pinned gamut = "X.Y" Usage snippets to the manifests, but release-plz bumps only the manifests. So every major bump, and every pre-1.0 minor bump of the umbrella, turns the release PR red.

This PR originally fixed that by rewriting the claims on the release branch with a script that parsed the guard's output. That approach kept the duplication and added a second parser. This version removes the duplication instead: the README states no version, so a release has nothing to update.

Change

  • Crates table (README.md): Status cells state disposition (stable, placeholder, an issue) and no version. Planned releases are written 1.0 ("1.0 under Release gamut-core v1 #177"). The section intro and the Releases note no longer refer to versions in the table.
  • Usage snippets (README.md, crates/gamut/README.md): cargo add gamut -F … replaces the pinned [dependencies] block. Cargo resolves the newest release and writes the caret requirement, so the snippet cannot go stale. That still covers README: the Usage snippet pins gamut = "0.1", three months behind the current release (supersedes #523) #559.
  • check-readme-crates/run.sh:
    • It refuses a vN/vN.M token anywhere in ## Crates, in rows and prose alike, instead of comparing it to cargo metadata.
    • In either README, it refuses a gamut = … line in any code block and requires a cargo add gamut line in one.
    • The manifest-comparison code is deleted.
  • fixtures.sh: the version and snippet fixtures are replaced to match these rules: tokens in a row or in prose, pins in inline-table, bare-string and nested-fence form, a deleted or unfenced snippet, cargo add gamut-png not counting, and the umbrella README's own copy.
  • release.yml is unchanged from master.

Verification

  • tooling/check-readme-crates/run.sh passes on the tree.
  • fixtures.sh passes 81/81 under both awk and gawk --posix.
  • Simulated chore: release #820: with gamut-isobmff at 4.0.0 and gamut at 0.5.0, the guard still passes with no README edit.
  • shellcheck -S warning is clean on both scripts, and convco check is clean.

Once this merges, the release-pr job regenerates #820 and the check passes with no extra commit on the release branch.

Closes #954

Decisions taken

  • 596a50a (pipefail SIGPIPE race in run.sh). grep -q exits at its first match. Under set -o pipefail the writer upstream of it then takes SIGPIPE, the pipeline fails, and the guard intermittently said a real crate was not a workspace crate. That was measured at 1 in 2000 calls on a loaded host, and the fixture battery hit it on "a cell naming a real crate". Both grep -q pipelines in run.sh now read a here-string instead of a pipe. The fix belongs in this PR because it made this PR's own fixture battery flaky.
  • 55c29f7 (the same race in fixtures.sh). The battery's fragment assertion (printf '%s\n' "$out" | grep -qF) ran under set -uo pipefail and had the same race. It could fail a fixture whose output did contain the fragment. It now reads <<<"$out", the same form as run.sh. I searched both scripts for any other | grep -q and found none.
  • 9726cd6 (umbrella docs.rs usage example). crates/gamut/src/lib.rs still pinned gamut = { version = "0.1", ... }, but the umbrella is at 0.4. It now shows cargo add gamut -F avif,jxl, the same form as both READMEs. I searched every crates/*/src module doc for a pinned gamut* = dependency line and found only this one. This PR does not extend check-readme-crates to read lib.rs. The guard's contract is the two READMEs, and the example now states no version, so it has nothing that can go stale.
  • Pre-existing check-spec-clauses failure (ci: spec-clauses mise tasks use set -o pipefail under sh, which is dash on ubuntu-latest #962). Format & Metadata also failed on master: the spec-clauses mise tasks ran under a non-bash shell. ci: run the spec-clauses mise tasks under bash #963 fixed that and has merged. 7127370 merges origin/master into this branch so the check runs against the fix. The merge commit has a Conventional Commit subject because the commit-msg hook rejects git's default merge message.
  • Paths beyond the Change list. mise.toml: only the check-readme-crates task description changes, so it matches the guard's new rule (Usage adds the umbrella with cargo add and pins no version). crates/gamut/src/lib.rs: see 9726cd6 above.
  • Local gates at 9726cd6. These passed: tooling/check-readme-crates/run.sh, fixtures.sh (81 passed, 0 failed), shellcheck -S warning on both scripts, cargo clippy -p gamut -- -D warnings, RUSTDOCFLAGS="-D warnings" cargo doc -p gamut --no-deps, mise run fmt-check, and the pre-commit hooks (fmt, clippy, convco). In this checkout, fmt-check and the fmt hook only ran with __CARGO_TEST_ROOT set to the checkout. The checkout is nested under another clone of the repository, and cargo walked up from the excluded tooling/lcms2-oracle into that clone's workspace. CI does not have this nesting. CI was disabled for this run, so CI is still the final gate.

release-plz bumps crate manifests but never the README, so every major
bump of a crates-table row's crate (or a pre-1.0 minor bump of the
umbrella) left the release PR red on check-readme-crates: the guard
held each row's `vN` token and the pinned `gamut = "X.Y"` Usage
snippets to the manifests, and nothing on the release branch moves them.

Rather than rewrite those claims on every release, stop writing them.
The crates table states disposition (stable, placeholder, an issue) and
no version; the Usage snippets become `cargo add gamut -F ...`, which
resolves the newest release itself and so cannot go stale (#559). The
guard now refuses a `vN` token in the section and a pinned `gamut = ...`
line in either README, and requires the `cargo add gamut` line, instead
of comparing either against cargo metadata.

Closes #954
@justin13888
justin13888 force-pushed the ci/release-pr-refresh-readme-versions branch from ca8d879 to e12910a Compare October 23, 2026 20:41
@justin13888 justin13888 changed the title ci(release): refresh README crate version claims on the release branch docs(readme): stop restating crate versions in the README Oct 23, 2026
… cannot refute a match

grep -q exits at its first match; under set -o pipefail the writer then
takes SIGPIPE and the pipeline fails, so the guard intermittently reported
a real crate as not a workspace crate (measured 1 in 2000 calls on a loaded
host; the fixture battery hit it on 'a cell naming a real crate'). Both
grep -q pipelines now read a here-string.
@justin13888
justin13888 merged commit 656fea9 into master Oct 24, 2026
@justin13888
justin13888 deleted the ci/release-pr-refresh-readme-versions branch October 24, 2026 18:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ci: refresh README crate version claims on the release-plz branch

1 participant