Bump File Format

Bump files are small markdown files that declare which packages changed and at what level, and a description to go into a changelog. They live in a .bumpy directory at your project root. Typically you create one per PR (although more is ok), and it is normal to have multiple pending bumps building up on main until a release.

When publishing (usually via CI), all pending bumps are merged into a single release plan, combining bumps and triggering bumps in dependencies as necessary. The bump files are deleted and changelogs are updated accordingly.

you may know these as "changesets" if coming from that tool

Basic syntax

A bump file has YAML frontmatter mapping package names to bump levels, and a markdown body that becomes the changelog entry:

---
'@myorg/core': minor
'@myorg/utils': patch
---

Added user language preference to the core config.
Fixed locale fallback logic in utils.

Tip: The description body is optional. If left blank, the bump file still contributes to the release plan (triggering version bumps and dependency propagation), but no entry will appear in the changelog for it. To keep a body as a note for reviewers while still omitting it from the changelog, set $changelog: false instead.

Bump levels

Level	When to use
major	Breaking changes
minor	New features (backwards-compatible)
patch	Bug fixes, minor improvements
none	Acknowledges a change without triggering a direct bump — useful for covering packages in --strict mode. Cascading bumps from other packages can still apply.

File naming

Bump file names are purely for human readability — bumpy doesn't derive any meaning from them. Use whatever makes sense for your workflow:

• Descriptive names like add-user-language.md or fix-login-timeout.md make it easy to see what's pending at a glance
• Auto-generated names (what bumpy add produces when --name is omitted) are fine when you don't want to think about naming

Creating bump files

Bump files are just markdown files — you can create them by hand, write them in your editor, or use the bumpy add CLI helper. Any .md file in .bumpy/ (other than README.md and _config.json) is treated as a bump file.

By hand

Create a file like .bumpy/add-user-language.md with the frontmatter and description. Name it whatever makes sense — a short description of the change is ideal. The filename doesn't affect behavior, it's just for human readability.

With bumpy add

The command is interactive and will create the file for you:

bumpy add

Or there is a non-interactive mode, helpful for AI assisted development:

bumpy add --packages "core:minor,utils:patch" --message "Added new features"

Flags:

• --packages <list> — comma-separated name:level pairs
• --message <text> — changelog description
• --name <name> — set the filename (auto-slugified). If omitted, a random name is generated.
• --empty — create an empty bump file (marks a PR as intentionally having no releases)
• --none — create a bump file with all changed packages set to none (acknowledge without bumping)

From branch commits

bumpy generate

Scans commits on the current branch and auto-creates a bump file. Works with any commit style:

• Conventional commits (feat(scope): ...) get bump levels from the commit type (feat → minor, fix → patch, feat! → major)
• All other commits are mapped to packages via changed file paths, defaulting to patch

See bumpy generate for full details.

Empty bump files

For PRs that intentionally don't need a release (docs, CI changes, etc.), create an empty bump file:

bumpy add --empty --name "docs-update"

This prevents bumpy check and bumpy ci check from failing due to missing bump files.

none bump type

Use bump type none to acknowledge that a package changed without triggering a direct version bump. This is useful when a package has internal-only changes (tests, config, etc.) that don't warrant a release on their own:

---
'@myorg/docs-site': none
---

This covers the package in bumpy check (including --strict mode) without producing a version bump or changelog entry. However, if another package's bump cascades to this package (e.g., via dependency propagation), the cascade will still apply normally.

To quickly set all changed packages to none:

bumpy add --none

Omitting an entry from the changelog

Sometimes a change warrants a version bump but isn't worth a changelog line (an internal refactor, a dependency tidy-up, etc.). You could leave the body blank, but that's easy to misread as "I forgot to write a description." The $changelog: false reserved key makes the intent explicit:

---
'@myorg/core': patch
$changelog: false
---

Internal refactor of the config loader — no user-facing change.

The bump still happens (and still cascades normally), but this file's body is omitted from both the changelog and GitHub release notes. The body is preserved in the bump file, so you can keep notes for reviewers without them leaking into public release notes.

$changelog is a file-level flag — a bump file has a single shared body, so it applies to every package the file lists. The $ prefix marks it as a reserved key; it can never collide with a package name (a package named changelog is still written changelog: patch, as a normal entry).

Per-package opt-out

If a single bump file covers several packages and you only want to suppress the changelog entry for some of them, use the nested object form's changelog: false instead. The shared body then renders for the other packages but is omitted for the flagged ones:

---
'@myorg/core': patch
'@myorg/internal-tooling':
  bump: patch
  changelog: false
---

Reworked the build pipeline.

Here @myorg/core's changelog gets the entry, but @myorg/internal-tooling's does not. The per-package flag composes with cascade, and stacks with the file-level $changelog: false (either one suppresses).

Cascade control (advanced)

You can explicitly push bumps to downstream packages using the nested object format:

---
'@myorg/core':
  bump: minor
  cascade:
    '@myorg/plugin-*': patch
    '@myorg/react': minor
---

New plugin API in core.

Cascade targets support glob patterns. This is useful when a change in one package should always trigger releases of specific dependents, regardless of the default propagation rules.