脚本版本管理应该遵循什么规范

本文目录导读：

1. 版本号规范：语义化版本（Semantic Versioning）
2. 命名规范：文件与标签
3. 提交规范：Conventional Commits（约定式提交）
4. 分支管理规范：推荐（GitFlow 或 Trunk-Based）
5. 版本管理核心原则总结
6. 一个简单的落地示例

脚本版本管理是保障代码可追溯性、团队协作效率及系统稳定性的关键环节，以下是遵循的规范，分为命名规范、版本号规范、提交规范和分支管理规范四个核心部分。

版本号规范：语义化版本（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.sh
  • data_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*

## [1.0.0] - 2024-05-20
### Breaking changes
- 重构配置读取方式，不再支持 config.ini，改为 config.yaml
### Features
- 新增多环境部署选项
### Bug Fixes
- 修复服务器连接超时问题