docs(publishing): record the version-bump trap that cost time cutting 0.4.0

[TheBlackBit]

In plain terms

Documentation only — one file, no code.

While cutting the 0.4.0 release, two things went wrong that the release checklist did not warn about. Both were figured out and worked around, but the knowledge ended up buried in a merged pull request description, where nobody cutting the next release would ever find it. This writes both into docs/PUBLISHING.md, which is the page you actually read when releasing.

What you're approving

• One file, docs/PUBLISHING.md. A new section, and one sentence added to the existing step 1 pointing at it. No code, no configuration, nothing that runs.
• Worst case if it's wrong: the documentation is inaccurate. Nothing breaks.

The two things being recorded

1 · The version-bump tool doesn't finish the job. These two packages are always released with the same version number, and one of them lists the other as a required package "version 0.3.1 or newer, but below 0.4.0". The standard command for bumping versions updates each package's own number but silently leaves that requirement line alone. Miss it, and you publish a new storefront that goes and downloads the old gate — the exact thing matching version numbers exists to prevent.

What makes it worth writing down is not the omission but how it announces itself. Halfway through, the build fails with:

error TS2305: Module '"@openmobilehub/credentagent-gate"' has no exported member 'Branding'

which reads like something is broken in the source code. Nothing is. The package is quietly reading a stale copy of the old version that got downloaded into a hidden folder. The section names the error, explains why it happens, and gives the fix — a plain npm install, since the abbreviated --package-lock-only form does not clear it.

2 · A shell habit that can make a failing build look like a passing one. Piping a command into tail to shorten its output replaces its success-or-failure signal with tail's, which always succeeds. A chained command sequence then continues as if everything passed. This happened during the 0.4.0 pre-flight: the build had failed and the test and lint steps ran anyway, and the result was briefly reported as green when it was not. The note says to check exit codes directly whenever a pre-flight result is going to be called green.

How to test

Read the rendered file on this branch and confirm the new section reads clearly and the link in step 1 jumps to it.

---

For reviewers — the detail

Section 1 — the dependency range

npm version X.Y.Z -w @openmobilehub/credentagent-gate -w @openmobilehub/credentagent-storefront --no-git-tag-version updates both version fields and leaves dependencies["@openmobilehub/credentagent-gate"] untouched. Because ^0.3.1 desugars to >=0.3.1 <0.4.0, a 0.4.0 storefront published with that range resolves a 0.3.x gate from the registry. The lockstep convention exists to keep the two in agreement, and this line is the only thing that actually enforces it at install time.

The observed failure chain, in order:

1. Workspace gate → 0.4.0; storefront still requests ^0.3.1.
2. npm can no longer satisfy that range from the workspace, so it installs the published 0.3.1 gate into packages/credentagent-storefront/node_modules/@openmobilehub/credentagent-gate.
3. npm install --package-lock-only, run after correcting the range, updates the lockfile but does not touch node_modules — the nested copy survives.
4. tsc --traceResolution confirms the resolution: successfully resolved to '…/packages/credentagent-storefront/node_modules/@openmobilehub/credentagent-gate/dist/index.d.ts' with Package ID '…@0.3.1'.
5. Branding is new in 0.4.0, so 0.3.1's declarations do not have it → TS2305.

The section documents the plain npm install as the fix and gives a one-liner asserting all three values (both versions and the range) read the new version.

Section 2 — the pipefail note

Written as a blockquote inside the same section rather than a heading of its own, since it is a caution about how you verify rather than a step in the process. Scoped deliberately narrowly — "whenever a pre-flight result is going to be reported as green" — rather than a blanket rule about pipes, which would be noise.

Placement

Step 1 of "How a release ships" gains a pointer; the section itself sits between "How a release ships" and "Optional polish", so it is adjacent to the step it concerns without interrupting the numbered sequence. The in-page anchor #the-version-bump-trap-npm-version-does-not-do-all-of-it matches GitHub's slug for the heading (backticks and parentheses stripped, spaces hyphenated) — verified against the heading text rather than assumed.

Both issues were hit cutting 0.4.0 in #162; this moves them from that PR body into the checklist.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
credentagent-demo	Ready	Preview	Jul 30, 2026 12:36am