本文目录导读：
- 版本号规范：语义化版本（Semantic Versioning）
- 命名规范：文件与标签
- 提交规范：Conventional Commits（约定式提交）
- 分支管理规范：推荐（GitFlow 或 Trunk-Based）
- 版本管理核心原则总结
- 一个简单的落地示例
脚本版本管理是保障代码可追溯性、团队协作效率及系统稳定性的关键环节，以下是遵循的规范，分为命名规范、版本号规范、提交规范和分支管理规范四个核心部分。
版本号规范：语义化版本（Semantic Versioning）
这是最广泛采用的规范，适用于库、工具脚本及API。
格式：主版本号.次版本号.修订号（5.1）
- 主版本号 (Major)： 当你做了不兼容的 API 修改（即破坏性变更）。
- 例子：接口参数彻底改变，输出格式完全重构。
- 次版本号 (Minor)： 当你做了向下兼容的功能性新增。
- 例子：新增了一个新的函数、新增了一个配置项、优化了性能。
- 修订号 (Patch)： 当你做了向下兼容的问题修正（Bug Fix）。
- 例子：修复了一个脚本崩亏的Bug、修正了拼写错误、修复了日志乱码。
特殊版本标识：
- 预发布版本： 在版本号后加
-alpha（内测）、-beta（公测）、-rc.1（候选版本）。0.0-beta.2
- 构建元数据： 在版本号后加 号，通常用于区分不同环境或构建时间。
0.2+20240501
脚本文件内声明建议： 在脚本头部使用注释或变量声明版本号和变更记录。
# 脚本名: data_cleaner.py # 版本: 1.3.1 修复了缺失字段报错的问题 # 日期: 2024-05-20 VERSION = "1.3.1"
命名规范：文件与标签
文件命名
- 原则： 小写、连字符 或下划线 ,不含空格。
- 不允许： 使用
v1.2_final、myscript_new这类模糊命名。 - 推荐格式：
脚本功能_版本号.后缀deploy-tool_v2.1.shdata_pipeline_v3.0.1.py
Git Tag（标签）
- 使用
v前缀,配合语义化版本。 - 推荐：
v1.0.0、v2.3.1-beta.1 - 不建议：
release、stable、最新版（无法区分具体版本）。 - 最佳实践： 每次发布正式版本时，必须打Tag,并附上说明。
提交规范：Conventional Commits（约定式提交）
清晰的提交历史直接决定了版本管理的质量，建议在 Git 提交信息中采用以下结构：
格式：<类型>(<作用域>): <简短描述>
常用类型：
feat: 新功能（对应次版本号升级）fix: Bug修复（对应修订号升级）docs: 文档更新style: 代码格式修改（不影响逻辑）refactor: 重构（既不修复bug也不增加功能）perf: 性能优化test: 增加测试chore: 构建过程或辅助工具的变动break: 破坏性变更（对应主版本号升级，通常用 或BREAKING CHANGE声明）
示例：
feat(deploy): 新增对AWS Lambda部署的支持 fix(parser): 修复当输入为None时脚本崩溃的问题 BREAKING CHANGE: API接口参数从get改为post，不再兼容旧版本 docs: 更新README中的安装步骤
为什么要这么做？
- 可以使用
standard-version、semantic-release等工具自动生成CHANGELOG。 - 可以自动判断下一个版本号（根据
fix还是feat还是BREAKING CHANGE）。
分支管理规范：推荐（GitFlow 或 Trunk-Based）
不同的团队规模选择不同策略：
小团队或短期脚本（推荐：主干开发）
main(或master): 始终是稳定且部署到生产环境的版本。- 开发者作业分支： 从
main拉出，完成后合并回main。 - 版本标签： 在
main上打v*
大型项目或多版本维护（推荐：GitFlow）
main: 记录历史版本。develop: 主开发分支。feature/xxx: 从develop拉出,开发新功能。release/v1.2.0: 从develop拉出，用于最终测试、修bug、更新版本号，完成后合并到main和develop。hotfix/v1.1.1: 从main拉出，紧急修复生产Bug，完成后同时合并回main和develop。
版本管理核心原则总结
| 原则 | 具体做法 |
|---|---|
| 永远不要修改已发布的版本 | 一旦打上Tag或发布，禁止对该版本的代码进行直接修改，有Bug就作为新版本发布。 |
| 破坏性变更必须升级主版本 | 如果旧脚本用户不修改自己的调用方式就无法使用，必须升主版本。 |
| 提交元数据要完整 | 每个版本必须包含：版本号、发布日期、变更日志（CHANGELOG）、责任人。 |
| 自动化是关键 | 使用 CI/CD 工具（如 Jenkins、GitHub Actions）自动检测提交类型，自动生成版本号，自动发布。 |
| 锁版本文件 | 如果是解释性脚本（Python、Node.js），确保 requirements.txt 或 package.json 中记录的依赖版本是明确的（==1.2.3 而非 >=1.2.3），避免环境差异导致脚本失效。 |
一个简单的落地示例
假设你有一个 Python 脚本 deploy_app.py：
- 初始状态：
v0.1.0(内部测试) - 你修了一个Bug：
git commit -m "fix: 修复服务器连接超时问题"→ 自动改为v0.1.1 - 你加了新功能：
git commit -m "feat: 新增多环境部署选项"→ 自动改为v0.2.0 - 你改变了主要API：
git commit -m "feat!: 重构配置读取方式，弃用旧命令"→ 自动改为v1.0.0
你的 CHANGELOG.md 应该清晰列出：
## [1.0.0] - 2024-05-20
### Breaking changes
- 重构配置读取方式，不再支持 config.ini，改为 config.yaml
### Features
- 新增多环境部署选项
### Bug Fixes
- 修复服务器连接超时问题遵循这套规范，任何接手脚本的人都能通过版本号快速判断升级风险,并通过提交历史快速定位问题。
