Giter VIP home page Giter VIP logo

release-please's Introduction

Google Cloud Platform logo

npm version codecov

Release Please automates CHANGELOG generation, the creation of GitHub releases, and version bumps for your projects.

It does so by parsing your git history, looking for Conventional Commit messages, and creating release PRs.

It does not handle publication to package managers or handle complex branch management.

What's a Release PR?

Rather than continuously releasing what's landed to your default branch, release-please maintains Release PRs:

These Release PRs are kept up-to-date as additional work is merged. When you're ready to tag a release, simply merge the release PR. Both squash-merge and merge commits work with Release PRs.

When the Release PR is merged, release-please takes the following steps:

  1. Updates your changelog file (for example CHANGELOG.md), along with other language specific files (for example package.json).
  2. Tags the commit with the version number
  3. Creates a GitHub Release based on the tag

You can tell where the Release PR is in its lifecycle by the status label on the PR itself:

  • autorelease: pending is the initial state of the Release PR before it is merged
  • autorelease: tagged means that the Release PR has been merged and the release has been tagged in GitHub
  • autorelease: snapshot is a special state for snapshot version bumps
  • autorelease: published means that a GitHub release has been published based on the Release PR (release-please does not automatically add this tag, but we recommend it as a convention for publication tooling).

How should I write my commits?

Release Please assumes you are using Conventional Commit messages.

The most important prefixes you should have in mind are:

  • fix: which represents bug fixes, and correlates to a SemVer patch.
  • feat: which represents a new feature, and correlates to a SemVer minor.
  • feat!:, or fix!:, refactor!:, etc., which represent a breaking change (indicated by the !) and will result in a SemVer major.

Linear git commit history (use squash-merge)

We highly recommend that you use squash-merges when merging pull requests. A linear git history makes it much easier to:

  • Follow history - commits are sorted by merge date and are not mixed between pull requests
  • Find and revert bugs - git bisect is helpful for tracking down which change introduced a bug
  • Control the release-please changelog - when you merge a PR, you may have commit messages that make sense within the scope of the PR, but don't make sense when merged in the main branch. For example, you may have feat: introduce feature A and then fix: some bugfix introduced in the first commit. The fix commit is actually irrelevant to the release notes as there was never a bug experienced in the main branch.
  • Keep a clean main branch - if you use something like red/green development (create a failing test in commit A, then fix in commit B) and merge (or rebase-merge), then there will be points in time in your main branch where tests do not pass.

What if my PR contains multiple fixes or features?

Release Please allows you to represent multiple changes in a single commit, using footers:

feat: adds v4 UUID to crypto

This adds support for v4 UUIDs to the library.

fix(utils): unicode no longer throws exception
  PiperOrigin-RevId: 345559154
  BREAKING-CHANGE: encode method no longer throws.
  Source-Link: googleapis/googleapis@5e0dcb2

feat(utils): update encode to support unicode
  PiperOrigin-RevId: 345559182
  Source-Link: googleapis/googleapis@e5eef86

The above commit message will contain:

  1. an entry for the "adds v4 UUID to crypto" feature.
  2. an entry for the fix "unicode no longer throws exception", along with a note that it's a breaking change.
  3. an entry for the feature "update encode to support unicode".

⚠️ Important: The additional messages must be added to the bottom of the commit.

How do I change the version number?

When a commit to the main branch has Release-As: x.x.x (case insensitive) in the commit body, Release Please will open a new pull request for the specified version.

Empty commit example:

git commit --allow-empty -m "chore: release 2.0.0" -m "Release-As: 2.0.0" results in the following commit message:

chore: release 2.0.0

Release-As: 2.0.0

How can I fix release notes?

If you have merged a pull request and would like to amend the commit message used to generate the release notes for that commit, you can edit the body of the merged pull requests and add a section like:

BEGIN_COMMIT_OVERRIDE
feat: add ability to override merged commit message

fix: another message
chore: a third message
END_COMMIT_OVERRIDE

The next time Release Please runs, it will use that override section as the commit message instead of the merged commit message.

⚠️ Important: This feature will not work with plain merges because release-please does not know which commit(s) to apply the override to. We recommend using squash-merge instead.

Release Please bot does not create a release PR. Why?

Step 1: Ensure releasable units are merged

Release Please creates a release pull request after it notices the default branch contains "releasable units" since the last release. A releasable unit is a commit to the branch with one of the following prefixes: "feat", "fix", and "deps". (A "chore" or "build" commit is not a releasable unit.)

Some languages have their specific releasable unit configuration. For example, "docs" is a prefix for releasable units in Java and Python.

Step 2: Ensure no autorelease: pending or autorelease: triggered label in an old PR

Check existing pull requests labelled with autorelease: pending or autorelease: triggered label. Due to GitHub API failures, it's possible that the tag was not removed correctly upon a previous release and Release Please thinks that the previous release is still pending. If you're certain that there's no pending release, remove the autorelease: pending or autorelease: triggered label.

For the GitHub application users, Release Please will not create a new pull request if there's an existing pull request labeled as autorelease: pending. To confirm this case, search for a pull request with the label. (It's very likely it's the latest release pull request.) If you find a release pull request with the label and it is not going to be released (or already released), then remove the autorelease: pending label and re-run Release Please.

Step 3: Rerun Release Please

If you think Release Please missed creating a release PR after a pull request with a releasable unit has been merged, please re-run release-please. If you are using the GitHub application, add release-please:force-run label to the merged pull request. If you are using the action, look for the failed invocation and retry the workflow run. Release Please will process the pull request immediately to find releasable units.

Strategy (Language) types supported

Release Please automates releases for the following flavors of repositories:

release type description
bazel A Bazel module, with a MODULE.bazel and a CHANGELOG.md
dart A repository with a pubspec.yaml and a CHANGELOG.md
elixir A repository with a mix.exs and a CHANGELOG.md
go A repository with a CHANGELOG.md
helm A repository with a Chart.yaml and a CHANGELOG.md
java A strategy that generates SNAPSHOT version after each release
krm-blueprint A kpt package, with 1 or more KRM files and a CHANGELOG.md
maven Strategy for Maven projects, generates SNAPSHOT version after each release and updates pom.xml automatically
node A Node.js repository, with a package.json and CHANGELOG.md
expo An Expo based React Native repository, with a package.json, app.json and CHANGELOG.md
ocaml An OCaml repository, containing 1 or more opam or esy files and a CHANGELOG.md
php A repository with a composer.json and a CHANGELOG.md
python A Python repository, with a setup.py, setup.cfg, CHANGELOG.md and optionally a pyproject.toml and a <project>/__init__.py
ruby A repository with a version.rb and a CHANGELOG.md
rust A Rust repository, with a Cargo.toml (either as a crate or workspace, although note that workspaces require a manifest driven release and the "cargo-workspace" plugin) and a CHANGELOG.md
sfdx A repository with a sfdx-project.json and a CHANGELOG.md
simple A repository with a version.txt and a CHANGELOG.md
terraform-module A terraform module, with a version in the README.md, and a CHANGELOG.md

Setting up Release Please

There are a variety of ways you can deploy release-please:

GitHub Action (recommended)

The easiest way to run Release Please is as a GitHub action. Please see google-github-actions/release-please-action for installation and configuration instructions.

Running as CLI

Please see Running release-please CLI for all the configuration options.

Install the GitHub App

There is a probot application available, which allows you to deploy Release Please as a GitHub App. Please see github.com/googleapis/repo-automation-bots for installation and configuration instructions.

Bootstrapping your Repository

Release Please looks at commits since your last release tag. It may or may not be able to find your previous releases. The easiest way to onboard your repository is to bootstrap a manifest config.

Customizing Release Please

Release Please provides several configuration options to allow customizing your release process. Please see customizing.md for more details.

Supporting Monorepos via Manifest Configuration

Release Please also supports releasing multiple artifacts from the same repository. See more at manifest-releaser.md.

Supported Node.js Versions

Our client libraries follow the Node.js release schedule. Libraries are compatible with all current active and maintenance versions of Node.js.

Client libraries targeting some end-of-life versions of Node.js are available, and can be installed via npm dist-tags. The dist-tags follow the naming convention legacy-(version).

Legacy Node.js versions are supported as a best effort:

  • Legacy versions will not be tested in continuous integration.
  • Some security patches may not be able to be backported.
  • Dependencies will not be kept up-to-date, and features will not be backported.

Legacy tags available

  • legacy-8: install client libraries from this dist-tag for versions compatible with Node.js 8.

Versioning

This library follows Semantic Versioning.

Contributing

Contributions welcome! See the Contributing Guide.

For more information on the design of the library, see design.

Troubleshooting

For common issues and help troubleshooting your configuration, see Troubleshooting.

License

Apache Version 2.0

See LICENSE

Disclaimer

This is not an official Google product.

release-please's People

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

release-please's Issues

Clean up release branches

Hello 👋,

Thanks for this great tooling. I've got a minor feature request which would help save a few clicks on the consumers end - would we be able to automatically delete release branches after they have been merged or marked inactive?

[PHP] Increment breaking changes as minor versions in pre-1.0 packages

We would like to take advantage of the conventional commits feature allowing highlighting of breaking changes, but Release Please considers any breaking change to be a major version update, even in pre-1.0 packages.

Release Please should increment the minor version for breaking changes when a package is in its pre-1.0 state rather than bumping to 1.0 (i.e. GA).

Thanks!

make test coverage less abysmal

the test coverage on release-please is quite low, I'd like to put some work into increasing it (now that we're starting to roll out to a wider audience).

ignore reverted commits

If we merge a feature, but then revert it, before the next release, we should be able to ignore the original PR from both the release history and the rules for version bumping.

chore(release): proposal for next release

🤖 This issue was created by robots! 🤖.

Its purpose is to show you what the next release of release-please would look like... If we published it right now.


1.2.0 (2019-05-10)

Bug Fixes

  • candidate issue should only be updated every 15 minutes. (#70) (edcd1f7)

Features

  • add GitHub action for generating candidate issue (#69) (6373aed)

[ ] Please open a PR for this release

parse commits for list of contributors

Some projects have a nice section of the release notes in GitHub that includes all the usernames of people who submitted contributions to that release.

unhandled rejection in Java tests

I'm noticing an unhandled rejection when running the test suite:

(node:227540) UnhandledPromiseRejectionWarning: HttpError: request to https://api.github.com/repos/googleapis/java-trace/issues/1/labels failed, reason: Nock: No match for request {
  "method": "POST",
  "url": "https://api.github.com/repos/googleapis/java-trace/issues/1/labels",
  "headers": {
    "accept": [
      "application/vnd.github.v3+json"
    ],
    "user-agent": [

Synthesis failed for release-please

Hello! Autosynth couldn't regenerate release-please. 💔

Here's the output from running synth.py:

Cloning into 'working_repo'...
Switched to branch 'autosynth'
Traceback (most recent call last):
  File "/home/kbuilder/.pyenv/versions/3.6.1/lib/python3.6/runpy.py", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "/home/kbuilder/.pyenv/versions/3.6.1/lib/python3.6/runpy.py", line 85, in _run_code
    exec(code, run_globals)
  File "/tmpfs/src/git/autosynth/autosynth/synth.py", line 256, in <module>
    main()
  File "/tmpfs/src/git/autosynth/autosynth/synth.py", line 196, in main
    last_synth_commit_hash = get_last_metadata_commit(args.metadata_path)
  File "/tmpfs/src/git/autosynth/autosynth/synth.py", line 149, in get_last_metadata_commit
    text=True,
  File "/home/kbuilder/.pyenv/versions/3.6.1/lib/python3.6/subprocess.py", line 403, in run
    with Popen(*popenargs, **kwargs) as process:
TypeError: __init__() got an unexpected keyword argument 'text'

Google internal developers can see the full log here.

chore(release): proposal for next release

🤖 This issue was created by robots! 🤖.

Its purpose is to show you what the next release of release-please
would look like... If you published it right now.

If you're a maintainer, and would like create a PR for this release,
simply comment on this issue.


1.0.0 (2019-05-10)

Bug Fixes

  • add ^ to dependency in samples/package.json (114a721)
  • allow executable (#11) (2b0219e)
  • could not handle the very first release of a library before it had any tags. (#24) (145fa1e)
  • log message was printing undefined version (#15) (1724969)
  • shebang must be first line (e8fe4bb)
  • support H2 and H3 CHANGELOG headings (#6) (39fd82f)
  • there was a typo in failure output (#61) (28e1489)

Build System

  • upgrade engines field to >=8.10.0 (#9) (49e7684)

Features

  • add a label to the release PR for automation (#4) (c3f0588)
  • adding a WIP GitHub action for minting releases (#27) (b159ef3)
  • adds support for updating release-dependent files in simple Node repo (#1) (775c0a8)
  • initial commit of library (c6dc492)
  • you must now opt in to bumping minor pre-major (#10) (f438ced)

BREAKING CHANGES

  • prior to this the minor was bumped rather than major for pre-major releases
  • upgrade engines field to >=8.10.0 (#9)

chore(release): proposal for next release

🤖 This issue was created by robots! 🤖.

Its purpose is to show you what the next release of release-please would look like... If we published it right now.


1.2.0 (2019-05-10)

Bug Fixes

  • candidate issue should only be updated every 15 minutes. (#70) (edcd1f7)

Features

  • add GitHub action for generating candidate issue (#69) (6373aed)

[ ] Please open a PR for this release

List Breaking Changes first

'Allo! I was just looking at this generated release, and I was thinking it would be nice if the BREAKING CHANGES came first on the list for maximum visibility. Actually, maybe even jazzing it up wouldn't be going too far:

⚠️ Breaking Changes!

Manually tagging a release causes permissions issues with future release PRs

Kokoro was experiencing an outage and we needed to get a release out so we manually tagged, circumventing the autorelease process. This prevented subsequent release PRs from being generated with the failure message command github-release failed with status 401 (See full log here).

As per @bcoe's suggestion, adding the autorelease-closed label to the release PR resolved the 401 - but it may be worth further investigating why this occurred in the first place.

Lots of closing/re-opening PRs

I noticed that we seem to have a lot of PRs getting closed, and re-opened with no changes:
image

It's generating a fair bit of notification noise, so I wonder if we can't first check if there is a PR open, and if it's latest commit # matches the previous one?

does not work on Node.js v8.16.0

fenster-macbookpro:release-please fenster$ node --version
v8.16.0
fenster-macbookpro:release-please fenster$ node ./build/src/bin/release-please.js mint-release --package-name=@google/repo [email protected]:googleapis/github-repo-automation.git
release-please.js mint-release

mint a new release for a repo

Options:
  --help                  Show help                                    [boolean]
  --version               Show version number                          [boolean]
  --token                 GitHub repo token
                           [default: "zzzzzz"]
  --package-name          name of package release is being minted for [required]
  --repo-url              GitHub URL to generate release for          [required]
  --release-type          what type of repo is a release being created for?
                                                               [default: "node"]
  --bump-minor-pre-major  should we bump the semver minor prior to the first
                          major release               [boolean] [default: false]
  --label                 label to add to generated PR
                                               [default: "autorelease: pending"]

TypeError: Symbol.asyncIterator is not defined.
    at __asyncValues (/Users/fenster/release-please/build/src/github.js:26:38)
    at GitHub.<anonymous> (/Users/fenster/release-please/build/src/github.js:100:31)
    at Generator.next (<anonymous>)
    at /Users/fenster/release-please/build/src/github.js:22:71
    at new Promise (<anonymous>)
    at __awaiter (/Users/fenster/release-please/build/src/github.js:18:12)
    at GitHub.allTags (/Users/fenster/release-please/build/src/github.js:96:16)
    at GitHub.<anonymous> (/Users/fenster/release-please/build/src/github.js:81:37)
    at Generator.next (<anonymous>)
    at /Users/fenster/release-please/build/src/github.js:22:71
$ jq .engines.node package.json 
">=8.10.0"

I guess the engines must be updated to support only those versions of Node.js that have async iterators.

develop more generic "update" class for long-tail of version replacements

Looking at google-api-java-client, there was a long tail of files we failed to update the version in:

./google-api-client/src/test/java/com/google/api/client/googleapis/GoogleUtilsTest.java:    String version = "1.30.3";
./google-api-client/src/test/java/com/google/api/client/googleapis/GoogleUtilsTest.java:    String version = "1.30.3-SNAPSHOT";
./google-api-client/src/main/java/com/google/api/client/googleapis/GoogleUtils.java:  public static final String VERSION = "1.30.3".toString();
./google-api-client-bom/README.md:      <version>1.30.3</version>

We continue to add one off fixes, like #304, but it might be nice to have a slightly more generic update class that handles a variety of simple string replacements.

e.g., <version>0.3.0</version>, VERSION = "0.20.4", maybe the class could support a variety of regexes like releasetool.

Open / close PR state is flapping

I was taking a look at this PR:
googleapis/nodejs-tasks#279

It looks like any time there was a push to master while the PR was open, the release PR got closed and then re-opened. Every time this happens, it pushes another GitHub notification to anyone watching the repo, and generally just generates a lot of noise. It would be nice to clean this up :)

fetch packageName parameter from repository itself

could we fetch the packageName from the repository itself, we already pull in package.json to update it... perhaps we could load the package.json earlier in the process, and use this value to override the packageName set in configuration.

Force push instead of close/open new PR

On gax-nodejs I saw that the first commit after landing the bot came through. The bot seems to close the existing release PR, and then just open a new one. Is it worth having the bot force push it's changes on the same PR instead of creating a new one?

chore(release): proposal for next release

🤖 This issue was created by robots! 🤖.

Its purpose is to show you what the next release of release-please would look like... If we published it right now.


1.2.0 (2019-05-10)

Bug Fixes

  • candidate issue should only be updated every 15 minutes. (#70) (edcd1f7)

Features

  • add GitHub action for generating candidate issue (#69) (6373aed)

[ ] Please open a PR for this release

Running at night

There are always gonna be a few releases we sit on for a bit. It seems like something is happening in a nightly cron somehow that's triggering the tool to get run:
image

It would be awesome if it only ran after things landed into master :)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.