Poetry 动态版本控制插件使用教程

1. 项目介绍

poetry-dynamic-versioning 是一个用于 Poetry 的 Python 插件，旨在通过版本控制系统（如 Git）中的标签实现动态版本控制。该插件由 Dunamai 提供支持，适用于 Python 3.7+ 和 Poetry 1.2.0+。通过这个插件，开发者可以在每次构建或发布时自动生成版本号，而无需手动更新版本信息。

主要功能

• 动态版本生成：基于版本控制系统中的标签自动生成版本号。
• 多种版本控制系统支持：支持 Git、Mercurial 等多种版本控制系统。
• 自定义版本格式：允许开发者根据需要自定义版本号的格式。
• 与 Poetry 无缝集成：作为 Poetry 的插件，可以直接通过 Poetry 命令行工具使用。

2. 项目快速启动

安装插件

首先，确保你已经安装了 Poetry。然后，使用以下命令安装 poetry-dynamic-versioning 插件：

poetry self add "poetry-dynamic-versioning[plugin]"

启用插件

在项目的 pyproject.toml 文件中启用插件：

[tool.poetry-dynamic-versioning]
enable = true

配置版本控制

你可以在 pyproject.toml 中进一步配置版本控制的选项，例如：

[tool.poetry-dynamic-versioning]
enable = true
vcs = "git"
style = "semver"

构建项目

启用插件后，每次运行 poetry build 或 poetry publish 时，插件会自动根据版本控制系统中的标签生成版本号。

poetry build

3. 应用案例和最佳实践

应用案例

假设你正在开发一个 Python 库，并希望每次发布时自动生成版本号。使用 poetry-dynamic-versioning 插件，你可以轻松实现这一目标。

1. 创建新版本：在 Git 中创建一个新的标签并推送到远程仓库。
2. 构建和发布：运行 poetry build 和 poetry publish，插件会自动根据最新的标签生成版本号。

最佳实践

• 使用语义化版本：建议使用语义化版本（Semantic Versioning）来管理版本号，这样可以更清晰地传达版本变更的信息。
• 定期更新标签：在每次发布新版本时，记得更新 Git 标签，以确保插件能够正确生成版本号。
• 自定义版本格式：根据项目需求，可以在 pyproject.toml 中自定义版本号的格式，以满足特定的版本控制需求。

4. 典型生态项目

poetry-dynamic-versioning 插件与以下生态项目紧密结合，提供了更强大的版本控制功能：

• Poetry：作为 Poetry 的插件，poetry-dynamic-versioning 可以直接通过 Poetry 命令行工具使用，简化了版本管理的流程。
• Dunamai：插件的核心功能由 Dunamai 提供支持，Dunamai 是一个用于动态版本生成的 Python 库，支持多种版本控制系统。
• PEP 517：插件支持 PEP 517 构建前端，可以在不同的构建环境中自动生成版本号。

通过这些生态项目的结合，poetry-dynamic-versioning 为 Python 开发者提供了一个强大且灵活的版本控制解决方案。