使用 GitHub Actions 和 Commitizen 自动发布 Python 库
介绍
维护 python 库可能具有挑战性，尤其是在发布新版本时。如果手动完成，该过程可能非常耗时且容易出错。在这篇文章中，我将引导您使用 github actions 和 commitizen 自动化发布过程。这种方法可确保您的版本保持一致，遵守语义版本控制 (semver)，并使您的变更日志保持最新，同时减少手动干预。
什么是语义版本控制？
语义版本控制（semver）是一种版本控制方案，它使用 major.minor.patch 格式的三个数字。该方案提供了一种清晰且可预测的方式来传达每个版本中的更改：
- 主要：重大更改 - 任何不向后兼容的内容。
- minor：新功能，但向后兼容。
- patch：错误修复——完全向后兼容。
语义版本控制至关重要，因为它可以帮助开发人员有效地管理依赖关系。当您知道库的新版本不会引入重大更改（例如，次要更新或补丁更新）时，您可以自信地更新您的依赖项，而不必担心应用程序崩溃。
有关 semver 的更多详细信息，您可以查看 semver.org。
承诺简介
commitizen 是一个标准化提交消息并自动执行版本控制和变更日志创建的工具。通过强制执行特定的提交消息格式，commitizen 可以确定所需的版本升级类型（主要、次要或补丁）并自动生成变更日志。
提交消息格式遵循以下结构：
(): the commit message
- 提交类型：
- feat：表示新功能。这可能会导致次要版本冲突。如果提交包含重大更改注释，则会导致主要版本更新。
- fix：表示错误修复并导致补丁版本提升。
- chore、ci 和其他：这些不会触发版本冲突。
例如：
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
在此示例中，壮举提交中的重大更改注释将触发主要版本更新。这种一致性可确保您的版本号传达正确的更改级别，这对于依赖您的库的用户至关重要。
配置 commitizen
要将 commitizen 与您的 python 项目集成，您需要在 pyproject.toml 文件中对其进行配置。以下是您需要添加的配置：
[tool.commitizen]
name = "cz_conventional_commits"
version = "0.1.0"
tag_format = "v$version"
version_files = [
"pyproject.toml:version",
]
update_changelog_on_bump = true
说明：
- name：指定要使用的提交消息约定。我们使用传统的提交格式。
- version：项目的当前版本。您应该从“0.1.0”或任何您的初始版本开始。
- tag_format：定义标签的格式，v$version 是典型格式（v1.0.0、v1.1.0 等）。
- version_files：列出跟踪版本号的文件。此设置可确保 pyproject.toml 中的版本号自动更新。
- update_changelog_on_bump：每当发生版本碰撞时自动更新 changelog.md 文件。
为什么要自动化发布过程？
手动管理版本可能很乏味并且容易出错，尤其是随着项目的增长。自动化带来了几个主要好处：
- 一致性：确保每次都以相同的方式处理版本升级和变更日志。
- 效率：通过减少发布新版本所涉及的手动步骤来节省时间。
- 准确性：最大限度地减少人为错误，例如忘记更新变更日志或错误地更新版本。
概述：自动发布过程
为了让您清楚地了解自动化的工作原理，这里有一个高级概述：
- 合并到主分支时：当拉取请求（pr）合并到主分支时，工作流程会检查提交消息，决定是否需要版本更新，更新变更日志，并在必要时标记发布。
- 关于标签创建：当推送标签（表示新版本）时，工作流程将新版本发布到 pypi 并创建带有相应变更日志的 github 版本。
拆分工作流程：合并事件与标签事件
为了简单明了，我们将自动化分为两个工作流程：
- 合并到主工作流程
- 关于标签创建工作流程
工作流程 1：合并到主流程
此工作流程处理检测更改和更新版本的逻辑：
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
说明：
- 触发器：当新的提交推送到主分支时，会触发此工作流程。
- 并发：并发设置可确保主分支一次仅运行一个工作流实例，从而防止竞争条件和重复的版本冲突。
- bump job：它检查提交消息是否以“bump:”开头，这表示来自先前版本的自动提交。如果没有，commitizen 根据提交消息确定必要的版本提升，更新 changelog.md，并创建一个新标签。
工作流程 2：标签创建
推送标签时会触发此工作流程，并处理发布过程：
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"
说明：
- 触发器：此工作流程由标签推送触发（例如，v1.2.0）。
- 并发：并发设置可确保每个标签仅运行一个工作流程实例，从而防止同一版本多次尝试发布等问题。
- 检测发布参数作业：提取版本的变更日志注释。
- 发布作业：构建包并使用 poetry 将其发布到 pypi。
- release-github 作业：使用生成的发行说明创建新的 github 版本。
设置个人访问令牌
为了确保工作流程可以执行创建提交和标记发布等操作，您需要在 github 存储库中设置个人访问令牌 (pat)：
- 转到 github 上的存储库。
- 导航到设置 > 秘密和变量 > 操作。
- 单击“新存储库秘密”。
- 添加名为 personal_access_token 的机密，并将您的 pat 粘贴到值字段中。
此令牌至关重要，因为它允许工作流程将更改（例如更新的变更日志和版本更新）推送回存储库。
生成的 changelog.md 示例
运行工作流程后，将自动生成并更新 changelog.md 文件。这是它可能的样子的示例：
## 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
每次发布新版本时，commitizen 都会自动更新此 changelog.md。它将更改分类为不同的部分（例如，feat、fix），使用户和开发人员可以轻松查看每个版本中的新增内容。
常见问题和故障排除
最后，这是工作流程创建后的 github 版本的样子：
-
不正确的令牌权限：如果工作流由于权限错误而失败，请确保 pat 具有必要的范围（例如，存储库、工作流）。
-
commitizen 解析问题：如果 commitizen 无法解析提交消息，请仔细检查提交格式并确保其与预期格式一致。
-
凹凸提交冲突：如果凹凸提交尝试合并到主分支时出现冲突，您可能需要手动解决冲突或调整工作流程来处理它们。
-
并发执行：如果没有适当的并发控制，同时处理多个提交或标签可能会导致重复版本冲突或竞争条件等问题。这可能会导致同一版本的多次提交或不完整的发布。为了避免这种情况，我们向两个工作流程添加了并发设置，以确保每个分支或标签一次仅运行一个实例。
结论和后续步骤
使用 github actions 和 commitizen 自动化 python 库的发布过程不仅可以节省时间，还可以确保一致性并减少人为错误。通过此设置，您可以更多地专注于开发新功能，而不是管理版本的重复任务。
下一步，请考虑扩展 ci/cd 管道以包括自动化测试、代码质量检查甚至安全扫描。这将进一步增强发布过程的稳健性。
号召性用语
如果您觉得这篇文章有帮助，请随时分享给其他可能受益的人。我很想听听您的想法或在下面的评论中可能提出的任何问题。您在项目中实施过类似的工作流程吗？分享你的经历！
参考文献和进一步阅读
- 语义版本控制官方网站
- 提交文档
- github actions 文档
以上就是使用 GitHub Actions 和 Commitizen 自动发布 Python 库的详细内容，更多请关注昆居客【www.kunjuke.com】。