You basically need three files:
a config file, to set up release-please options for each component
a manifest file, to specify the current version of existing components
a workflow file, to automate the release process for your repository
If your current repo has, for instance, a npm package under a subfolder named cherrycli. You'd need a basic config file to declare this component with its options:
// release-please-config.json
{
"separate-pull-requests": true,
"packages": {
".": {
"release-type": "python"
},
"packages/cherry-cli": {
"release-type": "node"
}
},
"$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"
}
If your package has already been published, declare its current version with:
// .release-please-manifest.json
{
".": "2.0.11",
"packages/cherry-cli": "1.0.9",
}
Finally, you'll need to automate the release process via GitHub Actions.
For that, you need to create a workflow file like below:
name: release-please
on:
push:
branches:
- main
permissions:
contents: write
pull-requests: write
jobs:
release-please:
runs-on: ubuntu-latest
steps:
- uses: googleapis/release-please-action@v4
Commit and push it all to your main branch.
From now on, release please will run against every commit that is merged into your main branch. It will look for conventional commits such as feat
, and decide whether it should publish a new minor, major, or patch version of your component.
It will also use the rest of the commit message to update your CHANGELOG.md.
How can I test before merging?
If you're making all the above changes inside the same pull request, and you want to try it out before merging, then you can change the target-branch to point to your current branch, and for it to run on pull requests:
name: release-please
on:
push:
branches:
- main
# For testing purposes, we'll force release-please to run
# on pull requests, so we can see the results of the action
# before merging it into the main branch.
pull_request:
permissions:
contents: write
pull-requests: write
jobs:
release-please:
runs-on: ubuntu-latest
steps:
- uses: googleapis/release-please-action@v4
with:
# The line below will force release-please to
# run on the current branch and, thus, be able to
# rely on the manifest file that we've just defined.
target-branch: <current-branch>
Conventional Commits
Conventional commits are a way to indicate to release-please what kind of changes you made. It'll then rely on the commit message to automate the bump of the version of your components, and to generate their changelogs.
Hereโs what a conventional commit message looks like:
<type>(<scope>): <description>
type: This tells you what kind of change it is. Common types include:
feat: A new feature
fix: A bug fix
docs: Documentation changes
style: Code style changes (like formatting)
refactor: Code changes that arenโt new features or bug fixes
test: Adding or updating tests
chore: Changes to the build process or tools
scope: This is optional and tells you which part of the codebase is affected, and depends on your own project's nature (like
web
orapi
).description: A brief summary of the change.
For instance:
git commit -m "feat(web): allow users to delete their accounts"
git commit -m "fix(api): handle null values in response"
Are there any other types?
Yes, additional types include perf, build, ci, revert, merge, wip. You can find details about all of them here: https://www.conventionalcommits.org/en/v1.0.0/
How does release-please know which version to bump?
In conventional commits, the type of version bump (patch, minor, or major) is determined by the nature of the changes indicated by the commit type.
Here's what happens for each type of commit:
fix: Patch Version (x.y.Z)
perf: Patch Version (x.y.Z)
feat: Minor Version (x.Y.z)
refactor: Minor Version (x.Y.z)
style: Minor Version (x.Y.z)
test: Minor Version (x.Y.z)
chore: Minor Version (x.Y.z)
Any commit with
BREAKING CHANGE
: Major Version (X.y.z)