推荐采用语义化版本（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）。
立即学习“Python免费学习笔记（深入）”；
- 示例：修正
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 包及简明升级说明，方便下游评估影响
