DOCSEARCHbyAlgolia
Submit Docs

cargo-release

repository·master·Indexed 23 days ago

https://github.com/crate-ci/cargo-release

A Cargo subcommand designed to streamline the Rust crate release process. It extends `cargo publish` by automating validation, version management (semver bumping), git tagging, and pushing. It supports workspaces, pre-release hooks, and custom file replacements to automate the release lifecycle.

Tokens
7.6K
Snippets
7
Records
49
Agent score
81%

What's inside cargo-release

  1. Overview of cargo-release features

    master

    cargo-release automates the crate release lifecycle with the following capabilities:

    Validation

    Ensures the repository is in a valid state for release by checking:

    • If you are on the correct branch.
    • If the local branch is up-to-date with the remote.
    • If the git tree is clean.

    Workspace Support

    Supports workspaces using native cargo flags like --workspace, --exclude, and --package. It automatically:

    • Updates dependent crates within the workspace when a version changes.
    • Uses change detection to identify which crates actually require a release.
    • Optionally shares commits.

    Release Automation

    • Handles cargo publish, git tagging, and pushing.
    • Pre-release search and replace: Allows for custom version updates, such as updating changelogs or updating tags in Dockerfiles.
    • Pre-release hooks: Provides hooks for extra customization, such as automated CHANGELOG generation.

  2. Understand bump levels and semver logic

    master

    When using the version step, you can specify a bump level or a specific version string. The behavior depends on the level provided:

    • release (default): Removes the pre-release extension (e.g., 0.1.0-alpha.1 -> 0.1.0).
    • patch: If a pre-release exists, removes it (0.1.0-alpha.1 -> 0.1.0). Otherwise, increments the patch field (0.1.0 -> 0.1.1).
    • minor: Bumps the minor version (0.1.0-pre -> 0.2.0).
    • major: Bumps the major version (0.1.0-pre -> 1.0.0).
    • alpha, beta, rc: Adds or increments the pre-release extension (e.g., 1.0.0 -> 1.0.1-rc.1, 1.0.1-rc.1 -> 1.0.1-rc.2).
    • [version]: Bumps to a specific valid semver string that is greater than the current version.

  3. Determine configuration precedence for cargo-release

    master

    cargo-release loads configuration from multiple sources. Settings provided via command line arguments have the highest precedence, followed by a file specified with --config PATH.

    Package Configuration Precedence:

    1. Command line arguments
    2. File specified via --config PATH
    3. $CRATE/Cargo.toml ([package.metadata.release] table)
    4. $CRATE/release.toml
    5. $WORKSPACE/Cargo.toml ([workspace.metadata.release] table)
    6. $WORKSPACE/release.toml
    7. Platform-specific config files:
      • Linux: $HOME/.config/cargo-release/release.toml
      • Windows: %FOLDERID_RoamingAppData%/cargo-release/release.toml
      • macOS: $HOME/Library/Application Support/cargo-release/release.toml
    8. $HOME/.release.toml

    Workspace Configuration Precedence:

    1. Command line arguments
    2. File specified via --config PATH
    3. $WORKSPACE/Cargo.toml ([workspace.metadata.release] table)
    4. $WORKSPACE/release.toml
    5. $HOME/.config/cargo-release/release.toml
    6. $HOME/.release.toml

    Note: Workspace inheritance is implicit and does not follow Cargo's standard workspace inheritance rules.

  4. Use cargo-release for a dry run or execution

    master

    By default, cargo release runs in dry-run mode, allowing you to verify the planned actions without making changes. To actually perform the release (version bumping, tagging, publishing, etc.), you must explicitly pass the --execute flag.

    Key behaviors:

    • Dry run (default): Shows what would happen.
    • Execution: Performs the release steps.
    • Logging: Increase verbosity with -v flags to see more details.
    • Verification Note: During the packaging and verifying steps, the output will show the current version rather than the bumped version because the tool delegates to cargo publish which is unaware of the in-memory version bump.

  6. Configure and use pre-release hooks

    master

    A pre-release hook is a custom command or script that runs automatically during the release process for a specific package. This is useful for custom automation like updating changelogs, running specialized tests, or notifying external services.

    Environment Variables

    When the hook is executed, the following environment variables are made available to the script:

    VariableDescription
    PREV_VERSIONThe previous version of the crate (bare version string)
    PREV_METADATAThe previous version's metadata
    NEW_VERSIONThe new version being released (bare version string)
    NEW_METADATAThe new version's metadata
    DRY_RUNSet to true if the release is running in dry-run mode, otherwise false
    CRATE_NAMEThe name of the crate
    WORKSPACE_ROOTThe absolute path to the workspace root
    CRATE_ROOTThe absolute path to the crate's root directory

    Template Rendering

    If the hook configuration in your Cargo.toml contains placeholders, they will be rendered using a template before execution. Supported tokens include:

    • prev_version
    • prev_metadata
    • version
    • metadata
    • crate_name
    • date (current timestamp)
    • tag_name (the planned git tag)

  7. Identify commit impact on package versions

    master

    The changes step analyzes Git commits between the previous release tag and the current HEAD to determine the impact on package versions. It uses Conventional Commits to categorize changes into a CommitStatus:

    • Breaking: Indicates a breaking change. Suggests a major version bump.
    • Feature: Indicates a new feature. Suggests a minor version bump.
    • Fix: Indicates a bug fix. Suggests a patch version bump.
    • Ignore: Commits categorized as chore, test, style, refactor, or revert are ignored and do not trigger version bumps.

    If the tool detects changes that require a bump but the version hasn't been updated yet, it will suggest the appropriate command, for example: cargo release version -p <crate_name> <patch|minor|major>

  8. Use pre-release hooks for custom release logic

    master

    The pre-release-hook configuration allows you to run a command before cargo-release commits the version change. If the command returns a non-zero exit code, the release process aborts.

    Available Environment Variables:

    • PREV_VERSION: Version before execution.
    • PREV_METADATA: Metadata before execution.
    • NEW_VERSION: Current (bumped) version.
    • NEW_METADATA: Current (bumped) metadata.
    • DRY_RUN: Whether the release is actually happening (true / false).
    • CRATE_NAME: Name of the crate.
    • WORKSPACE_ROOT: Path to the workspace.
    • CRATE_ROOT: Path to the crate.

    Placeholders can also be used within the hook arguments.

  9. Configure pre-release file replacements

    master

    Use the pre-release-replacements configuration key to specify files that should be searched and replaced with the new version during the release commit. This is an array of tables.

    Each table supports:

    • file: The file to search and replace.
    • search: A regex matching the string to replace.
    • replace: The replacement string (supports placeholders).
    • min (default 1): Minimum occurrences of search.
    • max (optional): Maximum occurrences of search.
    • exactly (optional): Exact number of occurrences required.
    • prerelease (default false): If true, run the replacement when bumping to a pre-release level.

  10. Use pre-release replacements for file updates

    master

    The replace step allows you to perform text replacements in specific files before a release occurs. This is useful for updating version strings, metadata, or dates in files that are not part of the Cargo manifest (e.g., documentation or specialized config files).

    When a replacement is triggered, the following variables are available in the template:

    VariableDescription
    prev_versionThe bare version string of the current (initial) version
    prev_metadataThe build metadata of the current (initial) version
    versionThe bare version string of the new (planned) version
    metadataThe build metadata of the new (planned) version
    crate_nameThe name of the package
    repositoryThe repository URL from the package metadata
    dateThe current timestamp (represented by NOW)
    tag_nameThe planned git tag name

    Replacements are only applied if the planned version is a pre-release, depending on your configuration.

  11. Execute a release with cargo-release

    master

    By default, cargo-release runs in dry-run mode, which simulates the release process without making any changes to your git repository or publishing packages. To actually perform the release (pushing tags and commits to the remote), you must use the --execute (or -x) flag.

    If you want to skip the interactive confirmation prompt and the version preview, use the --no-confirm flag.

  12. Configure commit messages for `cargo release commit`

    master

    The commit message used during the release process is generated from a template defined in your configuration. The tool supports several variables that can be used within the template string to customize the message.

    Available Template Variables

    When a package is committed, the following variables are available for rendering:

    • crate_name: The name of the crate.
    • version: The new version being released (bare version string).
    • metadata: The new version's build metadata.
    • prev_version: The previous version's bare version string.
    • prev_metadata: The previous version's build metadata.
    • date: The current timestamp (represented by NOW).

    In a workspace context, the tool attempts to find shared versions to generate a single consolidated commit message for the entire workspace.