Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration

Drop a release.toml in your repo root, or run jj-release init to generate one automatically. All fields are optional, defaults work for most GitHub + Rust projects out of the box:

manifest_backend = "cargo"           # manifest format: cargo, npm, go

[release]
trigger = "Release: please"          # commit message substring that kicks off a release
tag_prefix = "v"                     # prefix for version tags, e.g. v1.2.3
bookmark = "main"                    # bookmark to advance after release
forge = "github"                     # github, gitlab, forgejo, gitea, or none
create_release = false               # create a release on the forge after tagging
forge_url = ""                       # base URL for self-hosted forges

[bump]
# force = "minor"                    # override commit analysis: "major", "minor", or "patch"
# pre = "rc"                         # release pre-releases on this channel: 1.0.0-rc.1, -rc.2, …
features_bump_patch_before_1_0 = false  # before 1.0, release features as patches (0.4.1 → 0.4.2)

[publish]
cargo = false                        # set to true to publish to crates.io
cargo_flags = []                     # extra flags forwarded to `cargo publish`
semver_checks = true                 # run cargo-semver-checks before publishing
semver_checks_upgrade_major = false  # also upgrade pre-1.0 crates to a breaking bump

[changelog]
enabled = true                       # write a CHANGELOG.md entry on each release
file = "CHANGELOG.md"                # path to the changelog file
strict = true                        # drop unmapped/unformatted commits (false = "Other Changes")
link_headers = false                 # link each version heading to a forge compare view
layout = "root"                      # "root", "per-member", or "both" (workspaces)

# [aur]
# Required: The exact name of your package on the AUR
# package = "my-cli-tool"

# Optional: Override the default Git URL.
# Defaults to ssh://aur@aur.archlinux.org/{package}.git
# repo = "ssh://aur@aur.archlinux.org/custom-repo-name.git"

# [copr]
# Required: your COPR project as owner/project
# project = "your-username/my-cli-tool"

# Required: path to the spec, relative to the repo root
# spec = "packaging/rust-my-cli-tool.spec"

# Optional: wait for the COPR build to finish (default: false)
# wait = true

manifest_backend is a top-level key, so it must come before the first [table] header. TOML puts any key written after a header inside that table.

The forgejo and gitea forges are behind Cargo features of the same name.

Publishing

By default, jj-release only handles versioning, changelogs, tags, and forge releases. To automatically publish to crates.io, explicitly enable it in your configuration:

[publish]
cargo = true

Publishing can also be skipped per-run with --no-publish without editing release.toml, useful for testing the release pipeline or in scripts that handle publishing separately. --publish-cargo (-p) does the opposite.

Pre-releases are never sent to the AUR or COPR. Distro packages are only updated for stable versions.

Per-run overrides

These flags override release.toml for a single run, so there’s nothing to change and change back:

FlagOverridesExample
--bump <LEVEL>bump.force--bump major releases 1.0.0 from 0.x
--pre <CHANNEL>bump.pre--pre rc releases 1.0.0-rc.1, then -rc.2, …
--layout <LAYOUT>changelog.layout--layout both
--no-publish / -ppublish.cargo--no-publish

Versioning before 1.0

Before 1.0.0, Cargo treats the minor version as the breaking position, and jj-release follows it: a breaking change (feat!:, BREAKING CHANGE:) bumps the minor version (0.10.0 → 0.11.0), never the major. Moving to 1.0.0 is always your call:

jj-release --bump major

Features bump the minor version by default (0.4.21 → 0.5.0). For a library other crates depend on, release them as patches instead, so dependents requiring "0.4" pick them up without a requirement change:

[bump]
features_bump_patch_before_1_0 = true

Pre-releases

--pre <channel> (or bump.pre) releases the next pre-release instead of a stable version. A run without it promotes the latest pre-release to stable:

jj-release --bump major --pre rc   # 0.11.0 → 1.0.0-rc.1
jj-release --pre rc                # 1.0.0-rc.2
jj-release --pre beta              # refused: beta sorts below rc
jj-release                         # 1.0.0

Moving up a channel (alpha → beta → rc) restarts the number at .1.

Workspaces

jj-release init detects a Cargo workspace and writes this section for you:

[workspace]
enabled = true
versioning = "independent"           # "unified": one version for every member

[[workspace.members]]
name = "globset"
path = "crates/globset"
tag_prefix = "globset-"              # tags look like globset-0.4.22

[[workspace.members]]
name = "ignore"
path = "crates/ignore"
tag_prefix = "ignore-"
depends_on = ["globset"]             # members it depends on: sets publish order

With independent versioning, each member is released from its own tags and only when its files changed. When a member’s new version no longer satisfies another member’s requirement on it, that dependent is released too.

Version bumps in other files

jj-release bumps version = "..." in a flake.nix at the repo root automatically. For anything else, such as install snippets in a README, add a replacement:

[[replacements]]
file = "README.md"
search = 'my-crate = "[0-9.]+"'
replace = 'my-crate = "{{version}}"'
exactly_one = true                   # fail unless the pattern matches exactly once

replace can use {{version}}, {{crate_name}}, and {{date}}.

Changelog Configuration

You can customize how jj-release parses your commits and maps them to the Keep a Changelog format. By default, these commit types are included:

Commit typeChangelog section
featAdded
refactorChanged
perfPerformance
deprecate, deprecatedDeprecated
remove, removedRemoved
fixFixed
bugBug
securitySecurity
docsDocumentation

Anything else (chore, ci, test, unknown types, and messages that aren’t Conventional Commits) is dropped, or collected under “Other Changes” with strict = false. Breaking changes are marked **BREAKING** in their section.

Add these options to your release.toml to customize the behavior:

[changelog]
enabled = true
file = "CHANGELOG.md"
# Add emojis to the changelog headers
emoji_headers = true

# If true (default), commits that do not strictly match Conventional Commits
# or your prefix_mapping are silently dropped from the changelog.
# If false, unformatted commits are collected in an "Other Changes" section.
strict = false

# Commits to leave out of the changelog, matched as a whole word at the start
# of the message: "fix" excludes `fix: …`, `fix(cli): …` and `fix!: …`, but not
# "fixed a typo". Use "chore(deps)" to exclude only that scope.
exclude_prefixes = ["chore", "ci", "test", "WIP:"]

# Override specific default emojis (keys must match the exact Header name)
[changelog.emoji_mapping]
Added = "🚀"
Fixed = "✅️"
Bug = "🔥"
Performance = "⚡️"
Testing = "🧪"

# Map conventional commit types to custom Keep a Changelog headers.
# A mapped type is included even with strict = true. Custom headers appear
# after the standard ones, in alphabetical order.
[changelog.prefix_mapping]
revert = "Reverted"
test = "Testing"