docs: proposed prerelease channels design (RFC)

[theoephraim]

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:

• Branch = channel. Nominate a next / beta / etc. branch in .bumpy/_config.json. Pushing to it produces -rc.N / -beta.N versions on the matching dist-tag, using the same ci release flow as main.
• Bump files track state by directory. Pending at .bumpy/*.md, shipped at .bumpy/<channel>/*.md. ls .bumpy/ shows exactly what's pending vs shipped.
• No mode files. No pre enter / pre exit commands, no committed state file like changesets' pre.json.
• Promotion is a merge. next → main carries shipped bump files forward; main strips the suffix and consolidates everything into a single stable CHANGELOG.md entry.

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)

• Per-PR snapshot previews (0.0.0-pr-123-<sha>) — planned as a separate bumpy publish --snapshot flag.
• Workflow-dispatch one-off prereleases — planned as a complement to channels.
• Per-bump-file channel: frontmatter — not planned; channels stay branch-derived.

Test plan

• Reviewer reads docs/prereleases.md end-to-end.
• Sanity-check the lifecycle: does the directory-based marking model actually work for your team's workflow?
• Does the promotion flow handle the cases you care about (hotfixes during a cycle, target-raise mid-cycle, abandoning a cycle)?
• Anything missing — workflows you'd want supported on day one that aren't in the design?
• Comparison table with changesets is fair?

Nothing is built yet, so feedback can move freely on the design before we lock anything in.