说实话，Git 给我的迎头痛击已经多到数不清了。每次我以为终于理顺了发布流程，Git 就大喊一声：“没那么快！”紧接着两记刺拳、一记左勾拳、再来一记上勾拳，直接把我打趴在地，连发生了什么都不知道：分支不同步、合并冲突像打地鼠一样接连冒出来、版本号看上去更像彩票号码……简直一团糟。

不过，经历了无数次折腾、暂存，以及从错误中吸取教训之后，我终于摸索出了一套可以放心遵循的流程。不得不说，能确信最终发布到 PyPI 和 GitHub 的，就是我真正打算发布的代码，而不是最后一刻东拼西凑出来的“科学怪人”版本，这感觉真好。

下面说说我是怎么走到这一步的。

最初的挣扎

刚开始这个项目时，我根本没有分支策略。所有事情都直接在 main 上进行。这意味着，任何人在克隆仓库时，都很可能拿到一份无法正常工作的代码。

我是系统架构师，也真心认同 Git 及其丰富功能的价值。可我就是搞不清该如何有效地使用它。等到我开始探索分支、从分支再创建分支、合并这些奇妙操作时……只能说，我被折腾得够呛。事情经常失控，等我终于理顺一切，版本号已经从 0.15.0 变成了 0.15.8。

转折点

显然，我需要一个清晰、可重复的计划。于是我坐下来写了一份分支策略：main 用于稳定发布，dev 用于集成，feature 分支用于新功能，release 分支用于发布前的最后准备，bugfix 分支从 main 创建。这不只是高层次的说明，还包括我需要用到的每一条命令。说实话，它大概已经完善了 95%。

我不仅把这套流程记录在仓库里，也写进了项目之外的知识库。我的建议是：如果记录发布管理流程这件事本身就意味着要进行一次发布，那就别这么干……真的别。

实战经验

最让我开眼界的，是那次臭名昭著的 pyproject.toml 版本号冲突。main 和发布分支上的版本号不一样，Git 非要我选一边。我学会了快速识别和解决这些冲突，现在也只在发布分支上更新版本号。

另外，stash 是我的好朋友。当 main 一团乱时，我会先把那些改动暂存起来，完成合并，再丢弃暂存的内容，因为我压根儿就不想保留那些本地修改。这谈不上优雅，但确实救过我好几次。

胜利

终于，在完整演练了整个发布流程之后：创建功能分支、合并到 dev、创建发布分支、更新版本号、合并到 main、打标签、推送，我成功把代码发布到了 GitHub 和 PyPI，没有出现任何意外。

最棒的一刻？创建一个全新的虚拟环境，从 PyPI 安装自己的软件包，然后确认它正是我想要发布的那份代码。这才叫踏实。

给开发者同行的一些建议

  • 从简单的流程开始，再逐步改进。
  • 把发布检查清单放在仓库外部，确保它稳定而且随时可用。
  • 不要害怕合并或暂存改动。Git 是工具，不是暴君。
  • 只有手动流程足够可靠之后，再开始自动化。

另外，在一步步摸索这个流程时，也别不好意思请一位 Git 老手在旁边帮忙。

最后的想法

Git 大概还会继续揍我，但我已经不会吓得落荒而逃了。我有了计划、流程，以及一种掌握局面的感觉。如果你也在挣扎，那就坚持下去吧。Git 隧道尽头确实有光，而且值得为之努力。

你也有自己的 Git 战斗故事吗？我很想听听。

后续更新

我后来又写了一篇《Git 自动化》，讲的是怎样把这套流程自动化。