4.1 版本号相关实践#

首先根据语义化版本规范，规定版本格式为主版本号.次版本号.修订号。在初始开发阶段，以 0.1.0 为初始版本号，且后续每次发行都递增修订号，在 1.0.0 之前不需要对 API 的兼容性负责。以项目成熟、已经被多人依赖、并且开始考虑 API 的兼容性时作为正式发布阶段，以 1.0.0 作为起点，每次发行都递增版本号。

然后再考虑怎样让用户感知程序的版本。桌面程序一般是通过「关于」按钮，命令行程序一般是通过 --version/-v 选项获取版本。可以先看看自己所用到程序是怎样做的，再考虑自己怎样实现。

首先看看 VSCode 桌面程序的版本号是怎样体现的，单击帮助中的关于按钮后显示了如下信息：

1
Version: 1.56.2 (user setup)
2
Commit: 054a9295330880ed74ceaedda236253b4f39a335
3
Date: 2021-05-12T17:13:13.157Z
4
Electron: 12.0.4
5
Chrome: 89.0.4389.114
6
Node.js: 14.16.0
7
V8: 8.9.255.24-electron.0
8
OS: Windows_NT x64 10.0.19041

从以上可以很清晰地看到这个 VSCode 的软件版本号、提交 hash 值、构建日期以及上游软件/构建软件的版本号。通过这些信息我们基本就能重新构建出一个几乎一模一样的软件。

然后，再挑一个命令行程序 pypssh 查看它的版本号是怎样体现的，通过执行 pypssh version 后显示了如下信息：

1
地址: https://github.com/witchc/pypssh
2
版本号: v0.2.2
3
解释器版本: Python 3.7.4 (default, Jun  9 2021, 15:16:23)  [GCC 4.8.5 20150623 (Red Hat 4.8.5-44)]
4
发行版: Linux-4.19.104-microsoft-standard-x86_64-with-debian-10.9

从以上信息可以看出，它的输出和 VSCode 的「关于」菜单项输出的内容很是相似，都显示了构建环境和构建上游程序的版本。

其中 pypssh 的实现也比较简单：

1
@cli.command()
2
def version():
3
    """
4
    print version
5
    """
6
    addr = "https://github.com/witchc/pypssh"
7
    vno = "v0.2.2"
8
    interrupt_version = "Python " + ' '.join(sys.version.split('\n'))
9
    print(
10
        "\n".join
11
        ([
12
            f"Github: {addr}",
13
            f"Version: {vno}",
14
            f"Interrupt-Version: {interrupt_version}",
15
            f"Running-Platfrom: {platform.platform()}"
16
        ])
17
    )

基于以上实现，我们只需要保证每次发行时手动确保局部变量 vno 和 GitHub 中 tag 一一对应，即可实现一个简单的 --version 代码。通过特定发行版打印的版本信息，我们便能获取到对应的源代码以及构造一个一样的构建环境，从而进行发行版的重构建或者调试。

如果想在 --version 中携带更多的构建时信息，则可以采用构建时生成临时文件带入程序中的形式去展现，具体可以参考这个示例仓库。

4.2 提交消息最佳实践#

使用 VSCode 开发的项目，推荐使用 Conventional Commits 插件，该插件提供了标准的提交消息规范。若不使用 VSCode 开发，也可以使用最流行的提交消息规范工具 cz 提交消息。

CHANGELOG 的自动生成需要和方案多种多样，只要项目为提交消息制定了规范，那么自己也很容易能开发一个 CHANGELOG 生成工具，因为所需要的信息都在 git log 中了。

当完成当前版本所有开发计划后，便可以在 GitHub 上建立版本标签，将代码归档，并且开始新的版本计划。版本标签的命名规则需要遵循 semver。

4.3 持续集成实践#

目前比较流行容器化构建，因为容器化环境能确保构建的一致性。所以目前大多数代码管理平台都支持管道构建（PIPE BUILD），比如开源项目就可以选择 GitHub Actions 集成如 github-actions-golang 插件，实现较为标准的持续集成方案。由于不同平台都有不同的插件生态和语法，所以这里就不细聊了，具体参考平台文档和示例即可。比如 GitHub Actions 就可以参考博客 GitHub Actions 入门教程 - 阮一峰。

5.1 GitFlow#

GitFlow 由 Vincent Driessen 在 2010 年提出，是最早被广泛采用的 Git 工作流。它定义了两种长期分支和三种短期分支：

• 长期分支：main（生产代码）和 develop（开发集成分支）
• 短期分支：feature/*（功能开发）、release/*（发布准备）、hotfix/*（线上紧急修复）

GitFlow 的优点是分支职责清晰，适合有明确版本发布周期的项目。缺点是分支管理开销大，对于持续部署的项目来说过于繁琐。每次功能开发都要从 develop 拉出 feature 分支，合并回 develop，再从 develop 拉出 release 分支，最后合并到 main 和 develop。对于一天发布多次的 Web 项目，这个流程太重了。

5.2 GitHub Flow#

GitHub Flow 是 GitFlow 的简化版，只有一种长期分支 main，所有开发都基于短期分支：

1. 从 main 拉出描述性分支（如 fix-auth-bug）
2. 在分支上开发并提交
3. 开发过程中持续与 main 同步
4. 通过 Pull Request（PR） 进行代码审查
5. 审查通过后合并到 main
6. 合并后立即部署

GitHub Flow 的核心假设是：main 上的代码随时可以部署。这意味着每次合并前需要充分的测试和审查。它非常适合持续部署的 Web 项目和 SaaS（Software as a Service） 产品。

5.3 Trunk-Based Development#

Trunk-Based Development（主干开发） 是三种工作流中最激进的：所有开发者在 main（或 trunk）上直接提交，或者使用极短生命周期的分支（不超过一天）。

核心实践：

• 小批量提交：每次提交尽量小，频繁集成
• Feature Flag（功能开关）：未完成的功能用开关控制，不影响主分支部署
• 自动化测试：提交前跑完整测试套件，确保主干始终可用
• 短生命周期分支：如果用分支，必须在一天内合并

Google 和 Facebook 都采用这种方式。它的优势在于避免了合并地狱，因为每个人都频繁与主干同步。但前提是工程基础设施足够成熟：自动化测试覆盖率要高，Feature Flag 系统要完善，CI 要快。

5.4 三种工作流的选择#

对于刚起步的小团队，GitHub Flow 是最务实的选择。等团队和项目复杂度上来后，再考虑是否需要 GitFlow 的严格管控，或者向 Trunk-Based 演进。

7.1 Conventional Commits 规范#

Conventional Commits（规范提交） 是目前最流行的提交消息规范，格式如下：

1
<类型>(<范围>): <描述>
2

3
[可选的正文]
4

5
[可选的脚注]

常用类型：

feat 和 fix 之外的所有类型都归类为补丁，不触发版本号变更。如果某个 feat 或 fix 包含破坏性变更，在类型后加 !，或在脚注中加 BREAKING CHANGE:：

1
feat(api)!: 重构用户认证接口
2

3
BREAKING CHANGE: 登录接口从 /auth/login 迁移到 /api/v2/auth/login，
4
旧的 Authorization header 不再支持，需改用 Bearer token。

7.2 写好提交消息的技巧#

用祈使句写描述。写 “add feature” 而不是 “added feature” 或 “adds feature”。这样在 git log 中读起来更自然：“This commit will add feature”。

首行控制在 50 字符以内。首行是提交的”标题”，应该在 git log --oneline 中一目了然。详细信息放在正文中。

正文与首行空一行。Git 会把首行作为标题，正文作为详细信息，在 git log 和 GitHub 中呈现不同的样式。

解释 Why 而非 What。diff 已经展示了代码改了什么，提交消息应该解释为什么这样改。比如：

1
fix: 限制搜索结果最多返回 100 条
2

3
当数据量超过 10 万条时，未限制的查询会导致内存溢出。
4
100 条的限制覆盖了 99% 的使用场景，同时避免了 OOM。

拆分大提交。如果一个提交同时修改了功能、修复了 Bug、重构了代码，应该拆成三个提交。每个提交只做一件事，方便后续 git bisect 或 git revert。

7.3 工具辅助#

• commitizen/cz-cli：交互式提交消息生成器，引导你按规范填写
• commitlint：提交消息校验工具，配合 husky 在提交时自动检查格式
• VSCode Conventional Commits 插件：在编辑器中图形化填写提交消息

在 package.json 中配置 commitlint 和 husky 的示例：

1
{
2
  "devDependencies": {
3
    "@commitlint/cli": "^17.0.0",
4
    "@commitlint/config-conventional": "^17.0.0",
5
    "husky": "^8.0.0"
6
  },
7
  "commitlint": {
8
    "extends": ["@commitlint/config-conventional"]
9
  }
10
}

8.1 持续集成（CI）#

持续集成的核心目标：让主分支始终处于可部署状态。实现这个目标需要：

1. 提交时自动运行测试：每次 push 或 PR 都触发完整的测试套件
2. PR 合并前必须通过 CI：在 GitHub 中通过 branch protection rules 强制执行
3. 快速反馈：CI 跑完的时间控制在 10 分钟以内，越长开发者越容易忽略结果

GitHub Actions 的典型 CI 配置：

1
name: CI
2
on:
3
  push:
4
    branches: [main]
5
  pull_request:
6
    branches: [main]
7

8
jobs:
9
  test:
10
    runs-on: ubuntu-latest
11
    steps:
12
      - uses: actions/checkout@v4
13
      - uses: actions/setup-node@v4
14
        with:
15
          node-version: '20'
16
      - run: npm ci
17
      - run: npm run lint
18
      - run: npm run test
19
      - run: npm run build

8.2 持续部署（CD）#

持续部署在 CI 通过后自动将代码发布到生产环境。关键实践：

• 环境分离：dev -> staging -> production，每个环境有独立的部署流水线
• 金丝雀发布（Canary Release）：先部署到一小部分实例，观察指标正常后再全量发布
• 回滚机制（Rollback）：部署出问题时能快速回滚到上一个稳定版本

8.3 自动化版本发布#

结合 Conventional Commits 和 CI/CD，可以实现全自动的版本发布流程：

1. 开发者在 feature 分支上按规范提交
2. PR 合并到 main 后，CI 跑测试
3. 测试通过后，自动根据 commit 历史计算下一个版本号
4. 自动生成 CHANGELOG
5. 自动创建 Git Tag 和 GitHub Release
6. 自动发布到 npm / Docker Hub / 应用商店

这套流程可以用 release-please 或 semantic-release 实现。前者由 Google 维护，通过 PR 的方式管理发布；后者完全自动化，合并即发布。

8.4 常用 CI/CD 平台对比#