Snapshot & Pre-release Workflow
Relevant source files
The following files were used as context for generating this wiki page:
The Snapshot & Pre-release Workflow in pubm provides a mechanism for publishing temporary or preview versions of packages to registries without triggering a full production release. This system allows developers to test changes in real-world environments using "snapshot" versions (e.g., 1.0.0-snapshot.20231027) before committing to a final SemVer bump.
The workflow encompasses automatic version generation, prerequisite validation, test execution, and multi-registry publishing. It supports different versioning strategies for monorepos, including fixed and independent versioning, ensuring that version increments remain consistent across related packages.
Snapshot Pipeline Architecture
The snapshot pipeline is a specialized execution flow designed for high-velocity iteration. Unlike the standard release flow, it focuses on ephemeral versions and automated tagging.
Pipeline Execution Flow
The pipeline follows a strict sequence of tasks to ensure that only valid, tested code is published to registries as a snapshot.
The diagram above shows the linear progression of the snapshot pipeline from package filtering to final git tagging.
Sources: packages/core/src/tasks/snapshot-runner.ts:98-196
Component Responsibilities
| Component | Responsibility | Source |
|---|---|---|
applySnapshotFilter | Resolves and filters the package list based on user-provided path or name patterns. | packages/core/src/tasks/snapshot-runner.ts:25-39 |
buildSnapshotVersionPlan | Generates the VersionPlan (Single, Fixed, or Independent) based on current versions and the provided tag. | packages/core/src/tasks/snapshot-runner.ts:51-96 |
runSnapshotPipeline | Orchestrates the Listr tasks including testing, building, and publishing. | packages/core/src/tasks/snapshot-runner.ts:98-218 |
generateSnapshotVersion | Utility function that formats the version string using the base version and timestamp/tag template. | packages/core/src/tasks/snapshot-runner.ts:63 |
Pre-release & Versioning Logic
Pre-release versioning in pubm is driven by the project's versioning strategy and the current state of the git repository.
Versioning Strategies
The workflow adapts to three primary monorepo modes:
- Single: Used for projects with only one publishable package.
- Fixed: All packages in the monorepo share the same snapshot version.
- Independent: Each package receives a snapshot version derived from its own current version.
Sources: packages/core/src/tasks/snapshot-runner.ts:51-96, packages/core/src/tasks/phases/version.ts:46-240
Git Integration and Tagging
Snapshot releases create git tags to mark the specific commit published. For independent versioning, tags are formatted as {packageName}@{version}, while fixed/single versions use v{version}.
Sequence of events for ensuring tag uniqueness and pushing snapshot markers to the remote repository.
Sources: packages/core/src/tasks/snapshot-runner.ts:169-196, packages/core/src/tasks/phases/version.ts:79-114
CI/CD Integration
The workflow is designed to be highly compatible with CI environments like GitHub Actions. It differentiates between local and ci modes, adjusting the level of interactivity and the specific command flags used.
GitHub Actions Configuration
The system can automatically generate workflows for snapshot-like checks and releases.
- Changeset Check: A PR-level workflow that ensures every change has a corresponding changeset, preventing undocumented pre-releases.
- Release Workflow: Supports tag-based triggers (
v*) for single packages or commit-based triggers (e.g., "Version Packages") for monorepos.
Sources: packages/pubm/src/commands/init-workflows.ts:42-63, packages/pubm/src/commands/init-workflows.ts:153-210
Required Secrets for Pre-release
To publish in CI, the following environment variables are utilized by the tasks:
| Secret / Env Var | Registry Target | Description |
|---|---|---|
NODE_AUTH_TOKEN | npm / JSR | Authentication for JavaScript registries. |
CARGO_REGISTRY_TOKEN | crates.io | Authentication for Rust registries. |
GITHUB_TOKEN | GitHub | Used for creating GitHub Releases and pushing tags. |
Sources: packages/pubm/src/commands/init-workflows.ts:129-138, packages/core/src/tasks/phases/push-release.ts:88-100
Task Validation and Reliability
To ensure deployment reliability, the workflow includes several prerequisite checks defined in the localization and task modules.
Prerequisites Check
Before any snapshot version is written, the system verifies:
- The current branch is the designated release branch.
- The local working tree is clean (no uncommitted changes).
- The local history is synchronized with the remote (
git fetch/git pull). - New commits exist since the last release.
Sources: packages/core/src/i18n/locales/en.json:23-53
Registry Validation (Dry-Run)
The pipeline supports a --dry-run flag which allows users to validate the publish process without side effects. In this mode, the version bump is rolled back immediately after verification, and registries are called with their respective dry-run flags (e.g., npm publish --dry-run).
Sources: packages/core/src/i18n/locales/en.json:251-267, packages/pubm/src/commands/version-cmd.ts:114-122
Summary
The Snapshot & Pre-release Workflow provides a robust, automated pipeline for publishing intermediate versions. By integrating deep git awareness, monorepo versioning strategies, and mandatory validation checks, it ensures that pre-releases are as reliable as production releases. The architecture allows for seamless transitions between local interactive testing and automated CI/CD publishing, while the automatic rollback and restoration logic protects the integrity of the project's versioning history.