This content originally appeared on DEV Community and was authored by Antonis Markoulis
Introduction
Maintaining a Python library can be challenging, especially when it comes to releasing new versions. The process can be time-consuming and error-prone if done manually. In this post, I’ll walk you through automating the release process using GitHub Actions and Commitizen. This approach ensures that your releases are consistent, adhere to semantic versioning (semver), and keep your changelog up to date—all while reducing manual intervention.
What is Semantic Versioning?
Semantic Versioning (semver) is a versioning scheme that uses three numbers in the format MAJOR.MINOR.PATCH. This scheme provides a clear and predictable way to communicate what has changed in each release:
- MAJOR: Breaking changes—anything that is not backward-compatible.
- MINOR: New features, but backward-compatible.
- PATCH: Bug fixes—fully backward-compatible.
Semantic Versioning is crucial because it helps developers manage dependencies effectively. When you know that a new version of a library doesn’t introduce breaking changes (e.g., a minor or patch update), you can confidently update your dependencies without fear of your application breaking.
For more details on semver, you can check out semver.org.
Introduction to commitizen
Commitizen is a tool that standardizes commit messages and automates versioning and changelog creation. By enforcing a specific commit message format, Commitizen can determine the type of version bump required (major, minor, or patch) and generate a changelog automatically.
The commit message format follows this structure:
<commit-type>(<topic>): the commit message
- Commit Types:
- feat: Indicates a new feature. This can lead to a minor version bump. If a commit includes a BREAKING CHANGE note, it results in a major version bump.
- fix: Indicates a bug fix and leads to a patch version bump.
- chore, ci, and others: These do not trigger a version bump.
For example:
feat(parser): add support for parsing new file formats
fix(api): handle null values in the response
feat(api): change response of me endpoint
BREAKING CHANGE:
changes the API signature of the parser function
In this example, the BREAKING CHANGE note within a feat commit would trigger a major version bump. This consistency ensures that your version numbers communicate the right level of change, which is critical for users relying on your library.
Configuring Commitizen
To integrate Commitizen with your Python project, you need to configure it in your pyproject.toml file. Below is the configuration you'll need to add:
[tool.commitizen]
name = "cz_conventional_commits"
version = "0.1.0"
tag_format = "v$version"
version_files = [
"pyproject.toml:version",
]
update_changelog_on_bump = true
Explanation:
- name: Specifies the commit message convention to use. We’re using the conventional commits format.
- version: The current version of your project. You should start with "0.1.0" or whatever your initial version is.
- tag_format: Defines how tags are formatted, with v$version being the typical format (v1.0.0, v1.1.0, etc.).
- version_files: Lists the files where version numbers are tracked. This setup ensures that the version number in pyproject.toml is updated automatically.
- update_changelog_on_bump: Automatically updates the CHANGELOG.md file whenever a version bump occurs.
Why Automate the Release Process?
Manually managing releases can be tedious and prone to errors, especially as your project grows. Automation brings several key benefits:
- Consistency: Ensures that version bumps and changelogs are handled the same way every time.
- Efficiency: Saves time by reducing the manual steps involved in releasing a new version.
- Accuracy: Minimizes human error, such as forgetting to update the changelog or incorrectly bumping the version.
Overview: The Automated Release Process
To give you a clear picture of how the automation works, here’s a high-level overview:
- On Merge to Main: When a pull request (PR) is merged into the main branch, the workflow checks the commit messages, decides whether a version bump is needed, updates the changelog, and tags the release if necessary.
- On Tag Creation: When a tag is pushed (indicating a new release), the workflow publishes the new version to PyPI and creates a GitHub release with the corresponding changelog.
Splitting the Workflow: Merge vs Tag Events
For simplicity and clarity, we’ll split the automation into two workflows:
- Merge to Main Workflow
- On Tag Creation Workflow
Workflow 1: On Merge to Main
This workflow handles the logic of detecting changes and bumping the version:
name: Merge to Main
on:
push:
branches:
- "main"
concurrency:
group: main
cancel-in-progress: true
jobs:
bump:
if: "!startsWith(github.event.head_commit.message, 'bump:')"
runs-on: ubuntu-latest
steps:
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: "3.10"
- name: Checkout Repository
uses: actions/checkout@v4
with:
token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
fetch-depth: 0
- name: Create bump and changelog
uses: commitizen-tools/commitizen-action@0.21.0
with:
github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
branch: main
Explanation:
- Trigger: This workflow is triggered when a new commit is pushed to the main branch.
- Concurrency: The concurrency setting ensures that only one instance of the workflow runs at a time for the main branch, preventing race conditions and duplicate version bumps.
- bump job: It checks whether the commit message starts with ‘bump:’, which indicates an automated commit from the previous release. If not, Commitizen determines the necessary version bump based on the commit messages, updates the CHANGELOG.md, and creates a new tag.
Workflow 2: On Tag Creation
This workflow is triggered when a tag is pushed, and it handles the release process:
name: On Tag Creation
on:
push:
tags:
- 'v*'
concurrency:
group: tag-release-${{ github.ref }}
cancel-in-progress: true
jobs:
detect-release-parameters:
runs-on: ubuntu-latest
outputs:
notes: ${{ steps.generate_notes.outputs.notes }}
steps:
- name: Setup Python
uses: actions/setup-python@v5
- name: Checkout Repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Get release notes
id: generate_notes
uses: anmarkoulis/commitizen-changelog-reader@v1.2.0
with:
tag_name: ${{ github.ref }}
changelog: CHANGELOG.md
release:
runs-on: ubuntu-20.04
needs: detect-release-parameters
steps:
- name: Checkout repo
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.10"
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install poetry
- name: Configure pypi token
run: |
poetry config pypi-token.pypi ${{ secrets.PYPI_TOKEN }}
- name: Build and publish package
run: |
poetry publish --build
release-github:
runs-on: ubuntu-latest
needs: [release, detect-release-parameters]
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Create Release Notes File
run: |
echo "${{ join(fromJson(needs.detect-release-parameters.outputs.notes).notes, '') }}" > release_notes.txt
- name: Create GitHub Release
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
VERSION: ${{ github.ref_name }}
run: |
gh release create ${{ github.ref }} \
--title "Release $VERSION" \
--notes-file "release_notes.txt"
Explanation:
- Trigger: This workflow is triggered by a tag push (e.g., v1.2.0).
- Concurrency: The concurrency setting ensures that only one instance of the workflow runs for each tag, preventing issues like multiple release attempts for the same version.
- detect-release-parameters job: Extracts the changelog notes for the release.
- release job: Builds the package and publishes it to PyPI using Poetry.
- release-github job: Creates a new GitHub release with the generated release notes.
Setting Up the Personal Access Token
To ensure the workflows can perform actions like creating commits and tagging releases, you’ll need to set up a Personal Access Token (PAT) in your GitHub repository:
- Go to your repository on GitHub.
- Navigate to Settings > Secrets and variables > Actions.
- Click on New repository secret.
- Add a secret with the name
PERSONAL_ACCESS_TOKENand paste your PAT in the value field.
This token is crucial because it allows the workflow to push changes (like the updated changelog and version bump) back to the repository.
Generated CHANGELOG.md Example
After running the workflows, a CHANGELOG.md file will be generated and updated automatically. Here’s an example of what it might look like:
## v2.0.0 (2021-03-31)
### Feat
- **api**: change response of me endpoint
## v1.0.1 (2021-03-30)
### Fix
- **api**: handle null values in the response
## v1.0.0 (2021-03-30)
### Feat
- **parser**: add support for parsing new file formats
This CHANGELOG.md is automatically updated by Commitizen each time a new version is released. It categorizes changes into different sections (e.g., Feat, Fix), making it easy for users and developers to see what's new in each version.
Common Issues and Troubleshooting
Finally, here’s what a GitHub release looks like after being created by the workflow:
Incorrect Token Permissions: If the workflow fails due to permission errors, ensure that the PAT has the necessary scopes (e.g.,
repo,workflow).Commitizen Parsing Issues: If Commitizen fails to parse commit messages, double-check the commit format and ensure it's consistent with the expected format.
Bump Commit Conflicts: If conflicts arise when the bump commit tries to merge into the main branch, you might need to manually resolve the conflicts or adjust your workflow to handle them.
Concurrent Executions: Without proper concurrency control, multiple commits or tags being processed simultaneously can lead to issues like duplicate version bumps or race conditions. This can result in multiple commits with the same version or incomplete releases. To avoid this, we’ve added
concurrencysettings to both workflows to ensure only one instance runs at a time for each branch or tag.
Conclusion and Next Steps
Automating the release process of your Python library with GitHub Actions and Commitizen not only saves time but also ensures consistency and reduces human errors. With this setup, you can focus more on developing new features and less on the repetitive tasks of managing releases.
As a next step, consider extending your CI/CD pipeline to include automated testing, code quality checks, or even security scans. This would further enhance the robustness of your release process.
Call to Action
If you found this post helpful, please feel free to share it with others who might benefit. I’d love to hear your thoughts or any questions you might have in the comments below. Have you implemented similar workflows in your projects? Share your experiences!
References and Further Reading
This content originally appeared on DEV Community and was authored by Antonis Markoulis
Antonis Markoulis | Sciencx (2024-08-27T15:55:34+00:00) Automating Python Library Releases Using GitHub Actions and Commitizen. Retrieved from https://www.scien.cx/2024/08/27/automating-python-library-releases-using-github-actions-and-commitizen/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.