Pre release Cycles

Last synced from docs/engineering/process/prerelease-cycles.md on 2026-08-05. The repo file is the source of truth. If the two diverge, follow the repo.

This page describes pre-release cycles (beta, rc, next), a future addition to the release pipeline for @deessejs/fp. Pre-release cycles are not implemented today: there is no pnpm changeset pre enter workflow, no beta or rc dist-tags, no published pre-release packages on npm. This page documents the design so the concept is captured before it is forgotten.

Outline

1. What is a pre-release cycle
2. Why we would want pre-release cycles
3. Why we do not have pre-release cycles today
4. Target workflow
5. Known limitations
6. When to revisit this decision
7. Related documents

1. What is a pre-release cycle

A pre-release cycle is a phase between a major version bump and the stable release. While in this phase, every change publishes a version like 2.0.0-beta.0, 2.0.0-beta.1, 2.0.0-rc.0, etc., installable as @deessejs/fp@beta or @deessejs/fp@next. When the maintainer decides the API is stable, they exit the pre-release mode and the next change publishes the stable 2.0.0.

This is the Changesets pre-release mode. The trigger is a manual command (pnpm changeset pre enter beta), not a Git event like canary or hotfix.

2. Why we would want pre-release cycles

Three concrete benefits when shipping a major version:

• API stability window. Consumers can pin to 2.0.0-beta.N and test their code against it before the stable 2.0.0 lands. Breaking changes between beta versions are normal; breaking changes after 2.0.0 are not.
• External reviewers. People who want to validate the new API can install 2.0.0-beta.N without setting up a dev environment. Their feedback informs whether the API is ready.
• Marketing / coordination. Saying "2.0.0 is coming, here's the beta" is easier than "the main branch broke, sorry". Consumers have time to plan.

3. Why we do not have pre-release cycles today

• No major version on the horizon. @deessejs/fp is at 1.x. A 2.0.0 would require a deliberate breaking change, which is not planned. Pre-release cycles exist to support breaking-change work; without breaking-change work, the cycles have no purpose.
• Single-maintainer project. Pre-release cycles add overhead: every change during the cycle needs to publish under a beta dist-tag, the cycle must be ended explicitly, and consumers need to be notified. For a single maintainer shipping patches and minor versions, the overhead outweighs the benefit.
• No external consumers of bleeding-edge releases. Today's consumers run npm install @deessejs/fp and get the latest stable. There is no demand for beta channels.

When a major version becomes likely — and only then — pre-release cycles become useful enough to justify the overhead.

4. Target workflow

This is the spec for a future implementation, captured so it is not lost. The current implementation is the two-channel pipeline (stable + hotfix) plus the documented canary channel.

4.1 Enter pre-release mode

Manual command, run from a clean working copy on main:

pnpm changeset pre enter beta

After this command, the next pnpm changeset version produces versions like 2.0.0-beta.0 instead of 2.0.0. The --snapshot can also be combined for beta-on-every-commit.

4.2 Publish during pre-release

pnpm changeset publish --tag beta

This publishes under the beta dist-tag. Consumers install with npm install @deessejs/fp@beta.

4.3 Exit pre-release mode

pnpm changeset pre exit

After this command, the next pnpm changeset version produces the stable version (2.0.0). The beta dist-tag is not automatically removed; consumers who installed @beta continue to receive that version until they explicitly upgrade.

4.4 Tag names

Common conventions:

• next for the active development line (used by Next.js, React, etc.).
• beta for a major-version beta phase.
• rc for release candidates.
• Custom names for specific projects (e.g. experimental).

@deessejs/fp would use next for the active development line and beta / rc for major-version phases.

5. Known limitations

• Git event coupling. Pre-release mode is not tied to a Git branch. It is the maintainer's responsibility to enter and exit the mode at the right time. If the maintainer forgets to exit, every subsequent change publishes under the beta tag.
• Cross-channel pollution. While in beta mode, normal merges to main publish beta versions. Hotfixes also publish beta versions unless the maintainer exits the mode first, exits and re-enters, or uses the --snapshot flag to bypass.
• Consumer confusion. If a consumer has @beta in their lockfile and the maintainer exits pre-release mode, they keep getting the old beta version until they manually upgrade. Communication is essential.
• Trusted Publisher slot. Like canary, pre-release uses a different npm dist-tag, which means a separate Trusted Publisher entry is needed for the beta tag if you want OIDC.

6. When to revisit this decision

Re-open the pre-release question when any of the following becomes true:

• A major version is being planned (1.x → 2.x).
• The maintainer wants external testers for a breaking change before the stable release.
• A downstream consumer requests beta access explicitly.
• The project gains multiple maintainers who want to coordinate a major release.

Until one of these triggers fires, the simpler two-channel pipeline (stable + hotfix) plus the documented canary channel is enough.

7. Related documents

• Release Process — the current two-channel pipeline.
• Canary Snapshots — the per-PR snapshot channel.
• Hotfix Flow — the urgent-fix path.
• Internal: docs/engineering/process/prerelease-cycles.md — operational mirror of this page.
• External: Changesets Pre-releases — reference documentation for the underlying tool.