docs: rewrite publishing-guide.md against the actual 0.20.0 release process#11
Open
TjWheeler wants to merge 1 commit into
Open
docs: rewrite publishing-guide.md against the actual 0.20.0 release process#11TjWheeler wants to merge 1 commit into
TjWheeler wants to merge 1 commit into
Conversation
The previous version was missing the hard-won lessons from the last release cycle: - No coverage of the main vs master branch model - No pre-flight checklist (npm whoami, Dependabot, changeset audit) - No mention of pnpm changeset status --verbose as the pre-apply safety net that catches version-plan problems before they damage the working tree - Version bump described as a direct commit on main; should be on a branch and PR'd - Workspace References table claimed peerDependencies use workspace:^ for in-repo packages, but those have been removed - No troubleshooting section for the most common failure modes (1.0.0 escalation, missing fixed-group entry, stale changeset body, lockfile conflict with Dependabot) - The peer-dep rule was buried in a callout instead of being promoted to a discoverable Hard rules section - MFA expectations underspecified This rewrite captures the actual process used for 0.20.0: pre-flight → changeset → land work via PR → preview version plan → apply on a branch → PR the bump → publish from main → verify. Hard rules section codifies the constraints that prevent the 0.x to 1.0.0 escalation from returning. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Captures the hard-won lessons from the 0.20.0 release cycle that the previous guide was missing.
What changed
New sections:
main(default),development(integration),master(abandoned).peerDependencies(the 1.0.0 escalation trigger)fixedgroupnpm whoami, check for Dependabot PRs, audit changeset bodies for staleness, install + typecheck + test.pnpm changeset status --verbose) — the safety net we wished we had before runningversionblind. Shows what bumps will happen without applying them, with a stop-immediately list if the plan is wrong.0.x → 1.0.0jump, missing fixed-group entry, stale changeset body, Dependabot lockfile conflict, rollback procedure.Restructured:
chore/version-packages-X.Y.Z), not a direct commit onmain. Matches the auto-mode classifier guard and matches what we actually did for 0.20.0.Corrected:
Workspace Referencestable no longer claimspeerDependenciesis the convention for workspace-internal links — that pattern was removed in the peer-dep fix PR.dependenciesrow updated toworkspace:^→ caret range.Why this matters
The previous doc was technically accurate where it touched, but every gap was load-bearing: skipping
changeset statusmeant the 1.0.0 escalation only showed up after the working tree was damaged; missing Dependabot guidance meant a lockfile conflict surfaced mid-release; the buried peer-dep callout meant nobody noticed it until the action had been throwing 1.0.0 PRs for a while. Each gap cost us recovery time.This rewrite is structured so a future release can be driven straight from the doc, top to bottom, without diagnosis loops.