如何编写源代码控制提交消息

在提交源代码管理时，最好附上良好的提交信息，这似乎是人们要么完全遵循，要么完全忽略的事情之一。幸运的是，我现在主要独立工作，如果我的提交信息没有帮助，那也只能怪我自己。但我仍然会尽量遵循一些规则，以保证将来的正常运作。这些并非行业规则，只是我自己制定的标准，可以帮助我维护自己以及团队的代码库。

规则1：好的信息始于好的故事卡

有些人称之为故事卡、任务，或者其他任何名称，指的是从不太容易管理的主要任务（又称史诗任务）中抽取的一部分工作。无论你怎么称呼它们，许多项目都有某种形式的任务列表需要完成，我会利用这个列表来记录提交信息，以供日后参考。Jira 或 Mingle 等一些项目管理工具会自动为卡片分配一个编号，该编号会随着您的进度而递增。遗憾的是，我工作中使用的工具没有这样的功能，但我会手动为每张卡片的标题添加一个编号，以获得同样的好处。每张故事卡都应该有一个基本的标题，解释需要发生的事情。描述可以更深入地阐述解决方案和其他必要信息。

我写提交信息时，会先从要提交工作的故事卡号开始（你没看错——我尽量每个提交只写一张卡！）。在提交信息中提供卡号的好处在于，它能够准确地指出具体做了什么。如果你需要追溯到一周前，找出导致新 bug 出现的更改，可以查看过去一周的提交信息，看看哪些卡号被修改了，然后回到你的故事板进行进一步调查。

规则2：好的信息是描述性的

想象一下，你被要求检查一位同事上个月的提交。也许查看这些更改能帮你找到导致这个新 bug 的原因。你打开源代码管理管理器，看到如下信息：
2019年4月18日 - 提交内容
2019年4月15日 - asdf
2019年4月5日 - 周五会议前
2019年4月4日 - 完成内容
2019年4月1日 - 产品卡

当然，您可以查看每次提交中更改的每个文件，以了解发生了什么……但如果有更好的方法呢？如果每条源代码控制消息都简要概述了该提交所做的更改，会怎么样？此外，如果提交频率更高呢？4 月 5 日至 4 月 15 日之间可能发生了很多事情！我尝试每天至少提交一次；如果我在短时间内做了很多重大更改，我会每天提交几次。

重要的是，要为每条提交信息增添一些价值，无论你希望未来的自己、同事（或替代者）是否阅读它们。这个简单的举动可以节省大量时间，让他们能够一目了然地查看每组主要变更，而无需逐一检查。

规则3：好的信息解释什么，而不是如何或为什么

通过卡片编号将提交信息链接到故事板的另一个好处是，无需重复。如果你的卡片内容描述得非常详细，并展示了解决问题、创建功能等步骤，那么你无需在源代码管理中重复这些内容，因为只要按照卡片编号就能找到所有内容！

不过，你的源代码控制信息应该包含一些信息——我会尽量用一句话简要解释一下做了哪些更改。例如，可以这样写：“添加了客户商品选择清单”或“从主页移除了折扣按钮”。如果卡片的时间间隔较长，我会进行多次提交，简要更新这段时间内发生的工作：“实现了 Salesforce 登录功能的绑定创建”。

如果有人需要追溯到上周出现的 bug 的源代码控制，他们可以通过阅读消息来概览这段时间发生的更改。如果他们看到一条突出的消息，可能与代码中的问题部分有关，他们可以轻松参考编号，并在相关故事卡片中查看更详细的视图。故事卡片将为他们提供更改的方式和原因。

好消息看起来像……

那么，好的源代码控制提交是什么样的呢？以下是我工作中主要项目最近提交的一些示例：
卡片 #213 - 更新了报告表单的格式；
卡片 #213 - 添加了报告表单和第一份报告，用于获取和更新所有未处理的订单；
卡片 #208 - 更新了折扣查询；
卡片 #205 - 仅要求在关闭/电子邮件对话框中输入 SOM_SalesOrderID；
卡片 #204 - 将 SOM_UserDef5 和 SOM_FOB 更新移至 SalesOrder XML 创建之前；

TLDR：在进行源代码控制提交时，我会尽量保持信息简短、描述性强，并保持常规的格式。我还尽量为每个提交保留一个主要变更集或卡片，以避免变更集和信息混乱。