jj_release_core 0.11.0

Core library for jj-release: semantic releases for jj-vcs
Documentation

jj_release_core (Library)

The core automation engine behind jj-release. Provides a programmatic, trait-driven Rust API for interacting with Jujutsu (jj), parsing commits, resolving Semantic Versions, and orchestrating release pipelines. Can also be used directly to build custom release automation on top of Jujutsu.


Architecture

The library is built around a functional core that orchestrates releases using a set of pluggable backends. All side effects are abstracted behind traits, making it highly testable and extensible.

To run a release pipeline, you construct a ReleaseContext containing implementations for four core traits:

  • JjBackend: Interfaces with the Jujutsu VCS (e.g., ShellBackend).
  • ManifestBackend: Reads and writes project versions (e.g., CargoManifest, NpmManifest).
  • PublishBackend: Handles pushing artifacts to package registries.
  • ForgeBackend: Interacts with remote Git forges like GitHub, GitLab, Forgejo, and Gitea.

Beyond the core pipeline, the library also provides:

  • distro: publish to AUR and Fedora COPR after a crates.io release (behind publish-aur and publish-copr feature flags)
  • workspace: detect and manage multi-crate Cargo workspaces, including topological publish ordering and per-member version bumping
  • manifest: read and write version fields across Cargo, npm, and Go manifests without losing formatting, and update cross-member dependency versions
  • config: load release.toml and generate one automatically via generate_release_toml
  • detect: auto-detect forge, language, and workspace versioning strategy
  • registry: query crates.io for published versions as a release baseline
  • Replacements: update arbitrary files (README badges, spec files, docs) with version strings on each release

Usage

Add jj_release_core to your Cargo.toml:

[dependencies]
jj_release_core = "0.6.0"

Quick Start

use std::path::Path;

use jj_release_core::{
    config::Config,
    forge::NoForge,
    jj::ShellBackend,
    manifest,
    pipeline::{self, ReleaseContext},
    publish::NoPublish,
    errors::Result,
};

fn main() -> Result<()> {
    let root = Path::new(".");
    let backend = ShellBackend::new(root)?;
    let manifest = manifest::detect_manifest(root);
    let ctx = ReleaseContext::new(&backend, manifest.as_ref(), &NoForge, &NoPublish);
    let config = Config::default();

    // Generate a changelog preview
    pipeline::print_changelog(&ctx, &config, root, None, false)?;
    Ok(())
}

[!NOTE] ShellBackend requires jj on PATH.


Error Handling

All fallible operations return jj_release::errors::Result<T>, an alias for Result<T, ReleaseError>. The ReleaseError enum is powered by thiserror and covers IO, parsing, network, and release-specific failures, making it easy to pattern-match against specific failure states in your own applications.


Extending

Implement any of the core traits to customize behavior:

use jj_release_core::manifest::ManifestBackend;
use jj_release_core::errors::Result;
use semver::Version;

struct MyManifest;

impl ManifestBackend for MyManifest {
    fn read_version(&self, root: &std::path::Path) -> Result<Version> {
        // read version from your custom format
        todo!()
    }
    fn write_version(&self, root: &std::path::Path, version: &Version) -> Result<()> {
        // write version to your custom format
        todo!()
    }
}

Examples

See the examples/ directory for runnable demos:

  • generate_changelog: preview the next changelog section for commits since the last tag
  • full_changelog: regenerate the complete changelog from all tags in history
  • next_version: compute and print the next semantic version based on commits
  • validate_repo: run preflight checks to confirm a repo is ready to release
  • detect_env: detect forge, language, and workspace versioning strategy
  • init: preview the generated release.toml for a repository
  • run_release: demonstrates how to run the full pipeliine. Warning, this example makes real changes!
  • workspace_info: inspect workspace members, versions, and dependency order
  • bump_deps: update cross-member dependency versions without a full release

License