How OpenLogi Uses release-plz for Automated Workspace Versioning and Changelog Management

OpenLogi leverages the release-plz tool to automate version bumps across its entire Rust workspace while delegating changelog generation to git-cliff, creating a deterministic release pipeline that maintains a single source of truth for version numbers.

The OpenLogi repository employs release-plz to solve the complexity of managing multiple crates in a unified workspace. By configuring specific options in release-plz.toml and integrating with GitHub Actions, the project ensures that every crate version moves in lockstep while preserving clean git history and consistent release artifacts.

Unified Workspace Versioning Strategy

OpenLogi adopts a single-version policy across all publishable crates. In the root Cargo.toml, every crate inherits version.workspace = true, ensuring that version bumps propagate atomically throughout the entire workspace.

The release-plz.toml configuration defines a version group named openlogi that groups all crates under a common umbrella. This grouping ensures that when release-plz calculates the next semantic version based on conventional commits, it applies that single version number to every crate in the workspace simultaneously. This approach prevents version drift between interdependent crates and simplifies dependency management for downstream consumers.

Configuration-Driven Release Behavior

The repository centralizes release-plz behavior in [release-plz.toml](https://github.com/AprilNEA/OpenLogi/blob/master/release-plz.toml) at the project root. This configuration file explicitly disables several default behaviors to accommodate OpenLogi's application-specific release workflow:

• git_tag_enable = false for all crates except the root crate, ensuring only one Git tag (formatted as v{{ version }}) is created per release rather than per-crate tags.
• git_release_enable = false, which prevents release-plz from publishing GitHub Releases directly. Instead, the separate release.yml workflow handles final release publication after the tag is created.
• changelog_update = false, instructing release-plz to skip changelog modifications. OpenLogi handles changelog generation separately via git-cliff.
• semver_check = false, disabling cargo-semver-checks because OpenLogi ships as an application rather than a library, making API-breaking change detection unnecessary for release PRs.
• release_always = false, ensuring that Git tags and registry publications only occur when the release PR actually merges, preventing failed releases from creating orphaned tags.

Changelog Automation with git-cliff

Unlike typical release-plz setups that generate per-crate changelogs, OpenLogi uses git-cliff to produce a single repository-wide CHANGELOG.md. This design choice accommodates the workspace structure where GUI and agent applications are marked release = false and excluded from crate publishing, yet still need visibility in release notes.

When release-plz opens a release PR on a branch prefixed with release-plz/, the GitHub Actions workflow triggers [xtask/src/commands/release/changelog.rs](https://github.com/AprilNEA/OpenLogi/blob/master/xtask/src/commands/release/changelog.rs). This command executes git-cliff using the configuration in [.config/cliff.toml](https://github.com/AprilNEA/OpenLogi/blob/master/.config/cliff.toml), scanning all conventional commits since the last tag and rewriting the root CHANGELOG.md with the aggregated changes.

The workflow then pushes the updated changelog back to the release PR branch and replaces the PR body with the newly generated changelog section, ensuring reviewable release notes before merge.

CI/CD Pipeline Integration

The [.github/workflows/release-plz.yml](https://github.com/AprilNEA/OpenLogi/blob/master/.github/workflows/release-plz.yml) workflow orchestrates the automation. Running on every push to master, it executes the release-pr command to detect version-worthy changes and open a release PR.

The workflow uses a dedicated GitHub App token for authentication, allowing release-plz to trigger subsequent workflows when it pushes changelog updates. After the release PR merges, the same workflow (or a triggered follow-up) handles the actual publication, using [xtask/src/commands/release/checkout_version_bump.rs](https://github.com/AprilNEA/OpenLogi/blob/master/xtask/src/commands/release/checkout_version_bump.rs) to identify the correct commit SHA for tagging.

This split responsibility—where release-plz manages versioning and tagging while git-cliff and custom workflows handle documentation and distribution—creates a resilient pipeline where credential failures can be retried without duplicating version tags.

Local Development Commands

Developers can trigger release-plz operations locally using the xtask command suite before CI execution:

# Select and checkout the commit that will receive the version bump

cargo xtask release checkout-version-bump

# Verify that all publishable crates compile correctly for crates.io

cargo xtask release check-publish

# Generate the repository-wide changelog using git-cliff

cargo xtask release changelog --config .config/cliff.toml

These commands mirror the CI behavior, allowing maintainers to preview release changes before the automated workflow creates the PR.

Summary

• Unified versioning: All workspace crates use version.workspace = true grouped under a single release-plz version group named openlogi.
• Delegated changelog: release-plz skips changelog updates (changelog_update = false) in favor of git-cliff generating a single root CHANGELOG.md.
• Selective tagging: Only the root crate creates Git tags (v{{ version }}), while per-crate tagging remains disabled.
• Workflow separation: release-plz creates tags but does not publish GitHub Releases (git_release_enable = false), leaving final release creation and asset attachment to the separate release.yml workflow.
• Local tooling: The xtask command suite provides local equivalents for version bump selection, publish checks, and changelog generation.

Frequently Asked Questions

Why does OpenLogi use git-cliff instead of release-plz for changelog generation?

release-plz operates on a per-package basis and skips crates marked with release = false, which would exclude the GUI and agent applications from the changelog. By setting changelog_update = false in release-plz.toml and invoking git-cliff via the xtask workflow, OpenLogi generates a comprehensive repository-wide changelog that includes changes from all workspace members, regardless of whether they publish to crates.io.

How does OpenLogi ensure all crates share the same version number?

All crates in the workspace inherit their version from the root Cargo.toml using version.workspace = true. The release-plz.toml configuration defines a version group named openlogi that bundles all publishable crates together, causing release-plz to calculate a single next version based on aggregate conventional commits and apply that version uniformly across the entire group.

What happens if the release workflow fails after the PR merges?

Because release_always = false is configured in release-plz.toml, release-plz only attempts to create Git tags and publish to the registry when it detects a merged release PR. If the publication step fails due to credential issues or network errors, the workflow can be retried using the same commit SHA without creating duplicate tags, as the tag creation is idempotent and tied to the specific version bump commit.

Why are GitHub Releases disabled in release-plz configuration?

OpenLogi sets git_release_enable = false because the release process requires additional steps beyond what release-plz provides, specifically building and attaching DMG assets for macOS distributions. By disabling automatic GitHub Releases, the repository uses the tag created by release-plz to trigger the separate release.yml workflow, which builds application bundles, creates a draft release, attaches binaries, and handles final publication manually.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}