DOCSEARCHbyAlgolia
Submit Docs

release-please

repository·main·Indexed 25 days ago

https://github.com/googleapis/release-please

An automation tool that handles CHANGELOG generation, GitHub release creation, and version bumping by parsing Conventional Commit messages. It supports various release strategies for ecosystems including Node, Python, Go, Rust, Java, and more, and can be deployed via GitHub Action or CLI.

Tokens
22.8K
Snippets
38
Records
111
Agent score
85%

What's inside release-please

  2. Identify the Public API surface

    main

    The public interface of release-please is strictly limited to:

    1. The release-please CLI binary.
    2. Exported members from index.ts.

    All other classes and interfaces are considered internal implementation details and are subject to change without notice. Avoid importing from internal paths (e.g., release-please/src/internal/...) as these are not guaranteed to be stable.

  3. Understand Java Snapshot versioning

    main
    When using Java or Maven strategies, Release Please generates SNAPSHOT versions after each release. A SNAPSHOT is created as a separate "release" Pull Request that updates all affected files but does not trigger an actual release or a Git tag. These snapshot bump PRs are identified by the autorelease: snapshot label.

  4. Manually trigger a specific version number

    main

    To force Release Please to open a pull request for a specific version, include Release-As: x.x.x (case insensitive) in the commit body. This can be done using an empty commit.

    Example command:

    git commit --allow-empty -m "chore: release 2.0.0" -m "Release-As: 2.0.0"

  5. Understand the Release Please lifecycle

    main

    The release-please workflow automates the creation of release pull requests and GitHub releases based on your commit history. The standard lifecycle is:

    1. Commit: A commit is merged or pushed to your release branch (e.g., main).
    2. Propose: release-please opens a release pull request that proposes version bumps and appends release notes to your CHANGELOG.md.
    3. Review: A maintainer reviews and merges the release pull request.
    4. Release: release-please automatically creates a new GitHub release using the release notes extracted from the merged pull request.

    Note: release-please does not publish your packages or applications; it only manages the versioning and release metadata. You should set up separate automation to trigger publishing upon the creation of a GitHub release.

  6. Write Conventional Commits for automated versioning

    main

    Release Please uses Conventional Commit messages to determine SemVer bumps:

    • fix:: Correlates to a patch release.
    • feat:: Correlates to a minor release.
    • feat!:, fix!:, refactor!:, etc.: The ! indicates a breaking change, resulting in a major release.

    Note: To ensure a clean history and predictable changelogs, it is highly recommended to use squash-merges when merging pull requests.

  7. Use the `java` Strategy for Java projects

    main
    The java strategy is a general-purpose strategy for Java projects that does not automatically update any files. To manage version bumps in your project files (such as pom.xml or other configuration files), you must use the extra-files configuration to specify which files should be updated.

  9. Update Arbitrary Files with Annotations

    main

    Use the generic updater to update version information in arbitrary files by adding specific annotations (comments) to the file.

    Inline Annotations:

    • x-release-please-version
    • x-release-please-major
    • x-release-please-minor
    • x-release-please-patch

    Block Annotations: Start a block with x-release-please-start-version (or start-major, start-minor, start-patch) and end it with x-release-please-end.

    To force the generic updater, specify the type as generic in the extra-files configuration.

    {
  "extra-files": [
    {
      "type": "generic",
      "path": "path/to/file.yml"
    }
  ]
}

  10. Understand Release PR lifecycle and status labels

    main

    Release Please maintains 'Release PRs' that stay up-to-date as new work is merged into your default branch. When you are ready to release, merge the Release PR. Upon merging, Release Please updates changelogs (e.g., CHANGELOG.md, package.json), tags the commit with the version number, and creates a GitHub Release.

    Monitor the PR lifecycle using these status labels:

    • autorelease: pending: The initial state before the PR is merged.
    • autorelease: tagged: The PR has been merged and the release has been tagged in GitHub.
    • autorelease: snapshot: A special state for snapshot version bumps.
    • autorelease: published: A recommended convention indicating a GitHub release has been published based on the PR.

  11. Manage Java Bill of Materials (BOM) versioning

    main

    For pom.xml projects acting as Bill of Materials (BOM), Release Please infers dependency bump types from deps: commits. The semantic version bump of the BOM artifact must reflect the proposed version bump of its dependencies.

    For example, if a dependency undergoes a major version bump, the BOM artifact's version must also undergo an associated major version bump.