Changesets & Versioning
Relevant source files
The following files were used as context for generating this wiki page:
Changesets & Versioning in pubm provide a structured workflow for tracking changes, automating semantic version bumps, and generating changelogs across single-package projects and monorepos. The system allows developers to document intent-based changes as they occur, which are later consumed to calculate the next version of affected packages.
This system supports multiple versioning strategies, including Fixed (all packages share a version) and Independent (per-package versions), and integrates with CI/CD environments to automate the release process once changesets are merged into the main branch.
Sources: CLAUDE.md:143-150, plugins/pubm-plugin/skills/publish-setup/SKILL.md:173-180
Changeset Creation and Structure
A changeset is a Markdown file containing YAML frontmatter that maps package paths to bump types, followed by a summary of the changes. These files are stored in the .pubm/changesets directory.
Changeset Anatomy
Each changeset file includes:
- ID: A unique human-readable identifier (e.g.,
brave-ant-4f2z). - Frontmatter: A list of packages and their associated SemVer bump type (
patch,minor, ormajor). - Summary: A user-facing description of the change.
Sources: packages/core/src/changeset/writer.ts:80-112, packages/core/src/i18n/locales/en.json:435-438
Lifecycle of a Changeset
The following diagram illustrates the lifecycle from creation to consumption:
The system ensures that changesets are tracked in Git but prevents the .pubm directory from being bloated by ignoring the directory while explicitly allowing the changesets subdirectory via .gitignore rules.
Sources: packages/pubm/src/commands/init-workflows.ts:4-30, plugins/pubm-plugin/skills/publish-setup/SKILL.md:183-195
Versioning Strategies
The project supports three primary modes for versioning packages, determined during the version task phase.
| Mode | Description | Tag Format |
|---|---|---|
| Single | Used for non-monorepo projects with one primary package. | v{version} |
| Fixed | Monorepo strategy where all packages share the same version number. | v{version} |
| Independent | Monorepo strategy where each package is versioned based on its specific changesets. | {pkgName}@{version} |
Sources: packages/core/src/tasks/phases/version.ts:39-234, packages/core/src/i18n/locales/en.json:104-106
Recommendation Merging
The runVersionCommand uses mergeRecommendations to combine inputs from multiple sources (Changesets and/or Conventional Commits). Changesets typically take priority when calculating the final VersionBump.
The Versioning Workflow
The version command (or the version phase in a task runner) automates the transition from pending changesets to updated package manifests.
Execution Steps
- Analysis: Reads all files in
.pubm/changesets/and analyzes commit history if enabled. - Calculation: Determines the highest bump type for each package across all active changesets.
- Manifest Update: Writes new versions to
package.json,jsr.json, orCargo.toml. - Changelog Generation: Builds a new section in
CHANGELOG.mdusing the summaries from the consumed changesets. - Git Operations: Stages changes, creates a "Version Packages" commit, and generates appropriate Git tags.
- Cleanup: Deletes the consumed changeset files to prevent duplicate bumps in future releases.
Sources: packages/core/src/tasks/phases/version.ts:48-100, packages/pubm/src/commands/version-cmd.ts:133-149
Summary Table: SemVer Bump Logic
| Type | Usage |
|---|---|
| patch | Bug fixes or internal refactors with no API changes. |
| minor | New features that are backward-compatible. |
| major | Breaking changes or renamed public APIs. |
Sources: plugins/pubm-plugin/skills/publish-setup/SKILL.md:200-202, packages/core/src/i18n/locales/en.json:443-445
CI/CD Integration
pubm provides specialized workflows for GitHub Actions to automate changeset validation and publishing.
Changeset Check
A "Changeset Check" workflow runs on Pull Requests to ensure that any change to runtime code includes an accompanying changeset. This can be bypassed using a no-changeset label.
# Example Workflow Trigger
on:
pull_request:
types: [opened, synchronize, reopened, labeled, unlabeled]
Sources: packages/pubm/src/commands/init-workflows.ts:33-58, plugins/pubm-plugin/skills/publish-setup/references/ci-templates.md:214-230
Automated Publishing
In CI mode, the publish phase handles the actual distribution to registries. It relies on the versioning work performed in the previous prepare or version steps.
Sources: plugins/pubm-plugin/skills/publish-setup/references/ci-templates.md:7-15, packages/pubm/src/commands/init-workflows.ts:153-190
Data Structures
The versioning system relies on several key interfaces to manage the flow of data between the parser, the writer, and the task runner.
// From packages/core/src/changeset/parser.ts (as referenced in writer.ts)
export interface Release {
path: string; // File system path or package name
type: "patch" | "minor" | "major";
}
// From packages/pubm/src/commands/version-cmd.ts
export interface VersionBump {
currentVersion: string;
newVersion: string;
bumpType: "patch" | "minor" | "major";
}
Sources: packages/core/src/changeset/writer.ts:6, packages/pubm/src/commands/version-cmd.ts:21-25
Conclusion
The Changesets & Versioning system is designed to be highly reliable, featuring rollback handlers that can restore original versions, manifest backups, and delete created tags if the release process fails. By separating change documentation (changesets) from version execution (version command), it allows for collaborative development in monorepos without versioning conflicts.
Sources: packages/core/src/tasks/phases/version.ts:21-37, packages/core/src/i18n/locales/en.json:14-25