17370845950

推荐采用语义化版本（SemVer）X.Y.Z格式：主版本号升级表示不兼容API变更，次版本号升级表示向后兼容的新功能，修订号升级表示向后兼容的bug修复，并需配套git tag、CHANGELOG和依赖声明等工程实践。

Python项目版本管理推荐采用语义化版本（Semantic Versioning，简称 SemVer），即 X.Y.Z 格式：主版本号.次版本号.修订号。它不只是编号习惯，而是明确传达变更性质与兼容性承诺，对库维护、依赖管理、CI/CD 和团队协作至关重要。

主版本号（X）：不兼容的 API 变更

当项目做出破坏向后兼容的修改时，必须升级主版本号，例如删除函数、重命名公共接口、改变函数签名或返回值结构。此时，所有依赖该项目的代码都需人工审查和适配。

• 示例：requests 从 2.x 升到 3.x（假设有）会要求用户重写所有使用 Response.json() 或 session 行为的调用逻辑
• 建议：发布前运行完整兼容性测试；在 CHANGELOG 中显式标注 “BREAKING CHANGES”
• 注意：0.x 版本（如 0.9.1）表示初始开发阶段，不保证任何兼容性，主版本升到 1.0 才代表稳定公开 API

次版本号（Y）：向后兼容的功能新增

添加新功能但不破坏现有接口时递增。用户可安全升级，无需修改代码即可使用新能力，旧行为保持不变。

• 示例：为 pydantic.BaseModel 新增 model_dump_json(exclude_none=True) 方法，不影响已有 dict() 或 json() 调用
• 建议：新增功能需配套文档更新和单元测试；版本号升级需同步更新 __version__ 和 setup.py / pyproject.toml 中的 version 字段
• 注意：即使只改文档或新增非导出工具函数，只要没暴露新 public API，就不应升次版本号

修订号（Z）：向后兼容的问题修复

仅用于修复 bug、安全漏洞或性能微调，不引入新功能，也不改变任何已有行为。用户可无风险自动升级（如 pip install --upgrade）。

• 示例：修正 datetime.fromisoformat() 在处理带毫秒的 UTC 偏移字符串时的解析错误
• 建议：每个修复应关联 issue 编号；在 git tag 上打上 v1.2.3 并推送（注意前缀 v 是常见约定，非 SemVer 强制要求）
• 注意：若修复过程意外引入了兼容性问题，则该发布无效，需立即撤回并发布新修订版（如 1.2.4）

配套实践建议

语义化版本要真正生效，需结合工程规范：

• 用 setuptools_scm 或 versioneer 自动从 git tag 推导版本，避免手动维护出错
• 在 pyproject.toml 中声明 requires-python = ">=3.8"，并在 project.dependencies 中用兼容性标识，如 "requests >= 2.25.0,
• 每次发版前生成 CHANGELOG.md（可用 gitchangelog 或 towncrier），按 breaking / feature / fix 分类条目
• GitHub Release 页面应附带源码包（sdist）、wheel 包及简*级说明，方便下游评估影响