Release Please automates semantic versioning, changelog generation, and release pull request (PR) creation in the Gold Digger project by analyzing commit history according to the conventional commit specification. This enables a streamlined, hands-off release process that integrates with existing CI/CD workflows.

Release Process Overview#

The project supports both automated and manual release workflows. The manual process, documented in RELEASING.md, uses cargo-dist for artifact distribution and git-cliff for changelog generation. This approach provides maintainers with direct control over release timing and content. The automated Release Please workflow described below offers a hands-off alternative that is particularly useful for frequent, incremental releases.

Release policy and authority are governed by the project's governance framework, documented in GOVERNANCE.md. The maintainer has final authority over release cadence, version bumps, and which approach to use for a given release.

Automated Semantic Versioning and Changelog Generation#

Release Please monitors the main branch for new commits. When it detects conventional commit messages, it determines the appropriate semantic version bump (major, minor, or patch) and generates a changelog entry for each relevant commit. For example, a commit message like feat: add new output format triggers a minor version bump and adds an entry under "Features" in the changelog, while fix: resolve connection timeout issue triggers a patch bump and adds an entry under "Bug Fixes" source.

Configuration Details#

Release Please is configured via two files: .release-please-config.json and .release-please-manifest.json. The configuration file specifies the release type, package name, and changelog sections mapped to conventional commit types. For example:

{
  "packages": {
    ".": {
      "release-type": "rust",
      "package-name": "gold_digger",
      "changelog-sections": [
        {"type": "feat", "section": "Features", "hidden": false},
        {"type": "fix", "section": "Bug Fixes", "hidden": false},
        {"type": "perf", "section": "Performance Improvements", "hidden": false},
        {"type": "revert", "section": "Reverts", "hidden": false},
        {"type": "docs", "section": "Documentation", "hidden": false},
        {"type": "style", "section": "Style", "hidden": false},
        {"type": "refactor", "section": "Code Refactoring", "hidden": false},
        {"type": "test", "section": "Tests", "hidden": false},
        {"type": "build", "section": "Build System", "hidden": false},
        {"type": "ci", "section": "CI/CD", "hidden": false},
        {"type": "chore", "section": "Miscellaneous Chores", "hidden": true}
      ],
      "extra-files": ["Cargo.toml"]
    }
  }
}

The manifest file tracks the current version, for example:

{
  ".": "0.2.6"
}

source

The GitHub Actions workflow for Release Please is defined in .github/workflows/release-please.yml:

name: Release Please

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-22.04
    steps:
      - name: Run Release Please
        uses: google-github-actions/release-please-action@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          release-type: rust
          package-name: gold_digger

source

Integration with Existing Release Workflows#

Release Please creates release PRs with updated version numbers and changelogs. When a release PR is merged, it creates a git tag for the new version. The existing release workflow (.github/workflows/release.yml) is configured to trigger on these tags, handling artifact building, signing, and publishing. The workflow uses cargo-dist v0.31.0 for distribution and pins all GitHub Actions to specific commit SHAs (actions/checkout@v7.0.0, actions/upload-artifact@v7.0.1, actions/download-artifact@v8) for improved security and reproducibility. Build artifacts include attestations generated via actions/attest-build-provenance@v4, which provide cryptographically verifiable build provenance for supply chain security. This ensures that the release process is fully automated from commit to published release source.

name: Release

on:
  push:
    tags:
      - "v[0-9]+.*"
  workflow_run:
    workflows: ["Release Please"]
    types:
      - completed
  workflow_dispatch:
    inputs:
      tag:
        description: "Tag to release"
        required: true
        default: "v1.0.0"
# ... rest of release.yml

source

Conventional Commit Standards#

Release Please relies on the conventional commit specification to automate versioning and changelog generation. Commit messages must follow the format <type>[optional scope]: <description>, where type is one of feat, fix, docs, style, refactor, perf, test, build, ci, or chore. Scopes such as (cli), (db), (output), (tls), (config) are recommended for clarity. Breaking changes are indicated with an exclamation mark, e.g., feat!: migrate to new CLI interface. Properly formatted commits ensure that Release Please can accurately determine the type of version bump and generate organized changelog entries source.

Example Workflow#

1. Developer pushes conventional commits to the main branch.
2. Release Please analyzes the commit history and creates a release PR with updated version and changelog.
3. Maintainer reviews and merges the release PR.
4. Release Please creates a git tag for the new version.
5. The release workflow is triggered, building and publishing release artifacts.

Manual Release Process#

For manual releases, the maintainer controls the version bump and changelog generation process. The workflow is documented in RELEASING.md and follows these steps:

1. Create a release branch (release/vX.Y.Z)
2. Update the version in Cargo.toml
3. Generate the changelog using git-cliff (via just changelog vX.Y.Z)
4. Commit changes and open a PR to main
5. After merge, tag the release and push the tag to trigger the release workflow

Changelog generation uses git-cliff configured via cliff.toml, which applies the same conventional commit parsing rules as Release Please. The justfile includes changelog and release-notes recipes that wrap git-cliff invocations for consistent formatting.

See Also#

• RELEASING.md -- manual release process, pre-release checklist, artifact outputs
• GOVERNANCE.md -- release authority, decision-making process, maintainer roles
• docs/src/development/release-runbook.md -- detailed runbook with troubleshooting and recovery procedures
• cliff.toml -- git-cliff configuration for changelog generation
• implementation discussion and workflow configuration -- Release Please setup details