Skip to content

Fix four release-procedure defects found running v0.9.2 - #432

Open
dchud wants to merge 1 commit into
mainfrom
docs/release-procedure-fixes
Open

Fix four release-procedure defects found running v0.9.2#432
dchud wants to merge 1 commit into
mainfrom
docs/release-procedure-fixes

Conversation

@dchud

@dchud dchud commented Jul 28, 2026

Copy link
Copy Markdown
Owner

Running the v0.9.2 release end to end surfaced four defects in docs/contributing/release-procedure.md and one in scripts/lint-changelog.sh. All four bit during the actual release; none are hypothetical.

The version bump fails silently on macOS

Section 3.1 used sed's multi-line /range/{s///} form, which is a GNU extension. BSD sed rejects it with bad flag in substitute commandand still exits 0. The bump no-ops, and since the next step is cargo update --workspace, nothing downstream notices. A less careful run produces a chore(release) commit containing no version change. Replaced with POSIX awk and a verification step that exits non-zero on mismatch.

Section 7.1 contradicted Section 3.3

7.1 said stage exactly three files; 3.3 requires sweeping the README roadmap line, making four. Added README.md and a check for unstaged leftovers.

The lint warned on its own template, permanently

Section 4.2 seeds [Unreleased] with ### Performance and ### Documentation, neither of which lint-changelog.sh treated as canonical — so every run on every branch emitted a warning that could never be resolved. Both are genuinely used in released sections (Documentation 6 times, Performance 4), so the lint was wrong rather than the template. Added them after Fixed and synced the ordering in both places the doc states it. The warning is now gone.

Section 9.2 mutated the repository it was verifying

Worst of the four. cargo init inside the repo edits the root Cargo.toml, appending the test project to the workspace members list, and pulls the published crate into the root Cargo.lock. Deleting the test directory leaves both edits behind — they would have been committed silently if git status had not been checked.

It also makes the project a workspace member, so it inherits workspace lints and shares the root lockfile and stops resolving dependencies the way a downstream consumer does — meaning the check silently proves nothing. Both 9.1 and 9.2 now use the gitignored tmp/ instead of /tmp, 9.2 writes its manifest by hand with an empty [workspace] table, and the checklist asserts cargo metadata reports a registry+https://... source rather than LOCAL PATH.

Verification

Each fix was exercised rather than assumed: the awk bump was run against a copy of Cargo.toml and confirmed to change only the [workspace.package] line; lint-changelog.sh now exits 0 with no warning; the 9.2 isolation flow is the corrected one I actually used to verify 0.9.2 on crates.io. .cargo/check.sh passes.

No changes to release semantics — same steps, same order, same artifacts.

Checklist

  • .cargo/check.sh passes locally
  • Tests added or updated for the change — N/A, docs and a lint constant
  • CHANGELOG.md updated under [Unreleased] — N/A, contributor-facing tooling with no user-visible effect
  • Documentation updated — this is the documentation change
  • Python API changes follow pymarc conventions — N/A, no API change
  • Related tracked issue referenced — N/A, found during the release itself

🤖 Generated with Claude Code

Section 3.1's version bump used sed's multi-line `/range/{s///}` form,
a GNU extension. BSD sed (macOS) rejects it, prints "bad flag in
substitute command", and still exits 0 — so the bump silently no-ops
and the release proceeds at the old version. Replaced with POSIX awk
and a verification step that exits non-zero on mismatch.

Section 7.1 staged three files but Section 3.3 requires sweeping the
README roadmap line, making four. Added README.md and a check for
unstaged leftovers.

Section 4.2 seeds the [Unreleased] template with Performance and
Documentation, which lint-changelog.sh did not treat as canonical, so
every run warned. Both are used in released sections (Documentation
6 times, Performance 4), so the lint was wrong, not the template.
Added them after Fixed and synced the order in both places the doc
states it.

Sections 9.1 and 9.2 wrote scratch to /tmp and used `cargo init`
inside the repo. `cargo init` appends the test project to the root
Cargo.toml workspace members and pulls the published crate into
Cargo.lock; deleting the directory leaves both behind. It also makes
the project a workspace member, so it stops resolving dependencies
like a downstream consumer and the check proves nothing. Both now use
the gitignored tmp/ and a hand-written manifest with an empty
[workspace] table, plus an assertion that cargo resolves a registry
source rather than a local path.
@codspeed-hq

codspeed-hq Bot commented Jul 28, 2026

Copy link
Copy Markdown

Merging this PR will not alter performance

✅ 28 untouched benchmarks
⏩ 17 skipped benchmarks1


Comparing docs/release-procedure-fixes (7540237) with main (a3a55b8)

Open in CodSpeed

Footnotes

  1. 17 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports.

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.

1 participant