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

Release Process

token-privilege uses automated release tooling to minimize manual steps and ensure consistency.

Overview

Releases are managed by release-plz, which automates version bumping, changelog generation, and crate publishing. The process is driven by conventional commits on the main branch.

Conventional Commits

All commits must follow the conventional commits format:

<type>(<scope>): <description>

Types

TypePurposeVersion Bump
featNew featureMinor
fixBug fixPatch
refactorCode restructuringPatch
docsDocumentation changesNone
testTest additions or changesNone
choreMaintenance tasksNone
perfPerformance improvementsPatch
ciCI configuration changesNone

Scopes

ScopeWhen to Use
libPublic API in lib.rs
apiAPI surface changes
errorError type changes
elevationElevation detection logic
privilegePrivilege query logic
privilegesPrivilege constants module
ffiFFI boundary (unsafe code)
safetySafety invariant changes
securitySecurity-related changes
docsDocumentation
bookmdBook documentation
testsTest changes
ciCI workflows
depsDependency updates
releaseRelease-related changes

Special Rules

  • Changes touching unsafe code must use the ffi or safety scope and include the safety invariant in the commit body.
  • Cross-platform behavior changes must note the impact on Windows vs. non-Windows in the commit body.

Automated Release Flow

1. Push to main

When commits land on the main branch (via merged PR or direct push), release-plz runs two jobs:

2. Release PR

The release-plz-pr job analyzes commits since the last release, determines the appropriate version bump based on conventional commit types, and opens (or updates) a release PR. The PR contains:

  • Updated version in Cargo.toml
  • Generated changelog entries from commit messages

3. Release

The release-plz-release job detects when the version in Cargo.toml has been bumped and:

  • Creates a GitHub release with the changelog
  • Publishes the crate to crates.io

CI Pipeline

Every change goes through the following CI stages before it can be merged:

  1. Quality – rustfmt check and Clippy with -D warnings.
  2. Test – cargo nextest run on Ubuntu.
  3. Cross-platform – tests on Linux, macOS, and Windows.
  4. Coverage – cargo-llvm-cov with Codecov upload.
  5. Audit – cargo audit for known vulnerabilities.

All checks must pass before a PR can be merged.

Local Release Commands

For local testing and verification:

CommandDescription
just release-dry-runSimulate a release without publishing.
just releasePerform the release (requires credentials).
just release-patchRelease a patch version.
just release-minorRelease a minor version.
just release-majorRelease a major version.
just changelogGenerate the full changelog.
just changelog-unreleasedGenerate changelog for unreleased changes.

Changelog

The changelog is generated by git-cliff from conventional commit messages. Configuration is in cliff.toml.

To regenerate the changelog locally:

just changelog

To generate a changelog for a specific version:

just changelog-version v0.2.0