docs: proposed prerelease channels design (RFC)#104
Open
theoephraim wants to merge 6 commits into
Open
Conversation
Draft design doc for branch-based prerelease support. Models channels as long-lived branches (next, beta, etc.) with bump files tracked by directory location — pending at .bumpy/*, shipped at .bumpy/<channel>/, consolidated on promotion to main. Documents the comparison with changesets' pre mode and what's deliberately out of scope. Not yet implemented — sharing for user feedback before building.
Channels are for long-lived release lines (next/beta/rc), not per-PR previews. Add a "when to use this" section and point users at pkg.pr.new for ephemeral PR packages.
…dination Rewrite the dependency section around exact-pin-within-cycle, with cycle membership coming from explicit declarations (bump files, linked/fixed, cascadeTo) rather than automatic propagation. Drop the propagation config knob — matches bumpy's existing "explicit > implicit" stance for stable releases. Add a "Coordinating multi-package prereleases" section with the stranded-prerelease failure mode and the four ways to fix it. Update the changesets comparison table to reflect the new approach.
Re-thinking: semver only resolves a prerelease against a range when major.minor.patch matches exactly. That means every prerelease of an upstream breaks every dependent's range — not occasionally, but always. "Suppressing" cascade would just produce prereleases that consumers can't install together without manual overrides. So the right model is: Phase A/B/C run unchanged on channels, producing a wide cascade by nature of how prerelease semver matches. The user complaints behind changesets #960 are about bump-level policy (peer deps jumping to major), not about whether to cascade — and bumpy's proportional rules already address that. Drop the "Coordinating multi-package prereleases" stranded-failure section (no longer applies). Replace with a "Limiting cascade scope" note pointing at the existing ignore/include/managed controls. Update the changesets comparison row to reflect the actual difference.
After reviewing realistic prerelease workflows: between bumpy channels
(managed long-running release lines) and pkg.pr.new (ephemeral previews,
canaries, branch snapshots), real-world use cases are covered. No need
for an in-bumpy snapshot mechanism that would compete with the
recommended tool.
Expand the rule-of-thumb table to cover per-commit canaries and ad-hoc
branch snapshots. Reinforce the pkg.pr.new pointer in the day-to-day
workflow section so readers see it at the natural moment ("I want to
install this PR before merging").
…les, and tags Major revision of the channels design around one principle: git carries inputs (bump files) and stable outputs only. Prerelease versions exist solely in the registry and git tags. - package.json stays at the last stable version on channel branches - release PR becomes a pure file-move PR; computed versions go in the PR title and merge commit message (advisory; registry wins at publish) - counters derived from registry floor (max published + 1) — immune to abandoned cycles, force-resets, and re-runs - every publish recomputes the full cycle; lockstep republish + exact pins make the @next set coherent by construction - promotion is now just a merge; no suffix stripping, no rc versions ever on main, no version conflicts on main <-> channel syncs - generalized pending rule enables channel graduation (alpha -> beta) - no CHANGELOG.md on channels; GitHub releases + render-on-demand via bumpy status; consolidated stable entry written once at promotion - publish mechanics specified: trigger via channel-dir diff since last tag, tag-on-SHA idempotency, gitHead-based partial-failure resume - document build-time version baking caveat (rewrite before build) - reserve schema room for future stable/maintenance channels
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.
Summary
Draft design doc for branch-based prerelease support. Sharing for user feedback before building — please push back on anything that feels off.
The TL;DR of the design:
next/beta/ etc. branch in.bumpy/_config.json. Pushing to it produces-rc.N/-beta.Nversions on the matching dist-tag, using the sameci releaseflow asmain..bumpy/*.md, shipped at.bumpy/<channel>/*.md.ls .bumpy/shows exactly what's pending vs shipped.pre enter/pre exitcommands, no committed state file like changesets'pre.json.next→maincarries shipped bump files forward; main strips the suffix and consolidates everything into a single stableCHANGELOG.mdentry.The doc walks through the full lifecycle, dependency-cascade defaults, hotfix flow, counter behavior, and a side-by-side comparison with changesets' pre mode (with links to the specific known bugs the design avoids).
Why not just match changesets' pre mode?
Changesets' own docs describe their prerelease mode as "very complicated" with "mistakes that can lead to repository and publish states that are very hard to fix." The doc surveys the recurring complaints (#239, #381, #729, #786, #960) and aims to design them out rather than re-import them.
What's deliberately out of scope (for now)
0.0.0-pr-123-<sha>) — planned as a separatebumpy publish --snapshotflag.channel:frontmatter — not planned; channels stay branch-derived.Test plan
Nothing is built yet, so feedback can move freely on the design before we lock anything in.