一个好的提交信息的build议：格式/指南？
我在一个新项目的开始，我试图以一种聪明的方式build立知识库，并build立一些代码风格的指导方针，使每个人都能够专注于代码。
大部分工作已经完成，但是我仍然不确定应该为提交消息强制执行的格式。 我都是为了自由，只是告诉人们让他们清楚而彻底，但是我觉得这种做法很less有效，人们对“清楚”:)的概念非常不同。
到目前为止，我从来没有find一个令人满意的scheme。 我经常做的是：提交的一行摘要，然后是更详细地描述每个更改的项目符号。
但是，通常情况下，要确定哪些是值得要点的，哪些不是，按特征，文件或次要/重大更改进行某种分类似乎是合适的。 可悲的是，每次我尝试这样做，我最终都会写出愚蠢的长期提交消息来进行微小的更改…
你怎么做呢？
我认为你必须依靠那些真正能够为自己思考的人。 你可以提供一些基本的指导方针，就像你所描述的那样，但最终人们必须理解它们才能遵循它们。
以下是我推荐的版本控制最佳实践摘录：
在向存储库提交内容时总是写一个注释。 你的评论应该是简短的，并且要说明什么被改变了，可能是为什么。 如果您进行了多项更改，请对每个部分写一行或一句话。 如果您发现自己写了一个非常长的更改列表，请考虑将您的提交拆分成更小的部分，如前所述。 使用Fix或Add等标识符为您的评论添加前缀是指示您所做的更改的一种好方法。 这也使以后过滤内容更为容易，不论是在视觉上，由读者，还是由程序自动地过滤内容。
如果您修复了特定的错误或者实现了特定的修改请求，我也build议在提交信息中引用错误或问题编号。 某些工具可能会处理这些信息，并在缺陷跟踪系统中生成相应页面的链接，或根据提交自动更新问题。
下面是一些很好的提交消息的例子：
将段落分隔从缩进更改为垂直空间。 ... 修复：删除额外的图像。 修复：在javadoc中embeddedCSS以提供更好的结果。 在lyx中添加一个javadoc {@link}标签，以显示它是可能的。 ... - 将第三方项目移至ext文件夹。 - 为二进制库文件添加了lib文件夹。 ... 修正：修正错误＃1938。 添加：已实施更改请求＃39381。
根据我的经验，只要不遵守提交规则，你就必须跟进人员并给他们指示。 你当然可以实现一个脚本来强制执行一些规则（比如前缀和错误引用），但是这并不能抓住那些懒得写任何有意义的东西的懒惰的人。 我认为解释为什么要这些约定以及如何让开发团队受益非常重要。
设置提交邮件列表并监视邮件是跟踪人们在做什么的好方法。 每当有人没有一个令人满意的消息做某事，你会知道，可以告诉他们。 我想和编码惯例是一样的，因为他们要成功，有人必须跟随他们。
我试图遵循一些规则：
- 描述的第一行是对变化的简要概述。 许多源代码pipe理系统让你看到显示这一行的变化列表，所以它给了你一个粗略的总结。
- 包括错误ID 和错误标题。 不要让人们看起来！
- 如果您的错误跟踪支持，请将错误ID设置为打开错误的URL 。
- 说你改变了什么。
- 说你为什么做这个改变，而不是采取其他的方法。
- 非常详细 。
- 使每个更改变得更小使得更容易遵循历史，并且更容易编写和阅读良好的提交描述。
- 当一个改变是严格的重构时，我用
REFACTORING:开始第一行REFACTORING:。 这让我在寻找故意的function变化时忽略这种变化。 （当然，意外的function变化，即错误，仍然可以在这些中。）
有关高度详细的提交消息的示例，请参阅我的老朋友Cyrus的博客文章 。
我试图遵循这些规则：
- 简明扼要
- 描述你为什么做，而不是你做什么
我的提交消息的通常格式是：
Issue: #[issue number] [short description]
如果您有某种错误跟踪系统，请在提交消息中提供问题编号。
我发现许多开发人员只是写了一些像“添加X.删除Y”，但我可以find这个信息看代码差异。 如果没有附加的问题编号，可能很难知道为什么开发者做了一些改变。
我非常喜欢angular.js提供的格式 ：
Git提交准则
我们对如何格式化git commit消息有非常精确的规则。 这导致更多可读的消息 ，通过项目历史浏览时很容易遵循。 而且，我们使用git commit消息来生成AngularJS更改日志 。
提交消息格式每个提交消息由一个头部 ，一个主体和一个页脚组成 。 标题有一个特殊的格式，包括一个types ，一个范围和一个主题 ：
<type>(<scope>): <subject> <BLANK LINE> <body> <BLANK LINE> <footer>任何提交消息的行不能超过100个字符！ 这使得消息在github上以及在各种git工具中更容易阅读。
types必须是以下之一：
- 专长 ：一个新function
- 修复 ：一个错误修复
- 文档 ：仅文档更改
- 样式 ：不影响代码含义的更改（空白，格式化，缺less分号等）
- 重构 ：代码更改既不修复错误也不添加function
- perf ：改进性能的代码更改
- testing ：添加缺less的testing
- 杂项 ：对构build过程或辅助工具和库（如文档生成）的更改
范围范围可以是任何指定提交更改的地方。 例如
$location，$browser，$compile，$rootScope，
ngHref，ngClick，ngView等…主题主题包含对变更的简要描述：
- 使用命令式，现在式：“变”不变“也不变”
- 不要把首字母大写
- 没有点（。）在最后
正如在主题中 ，使用命令式，现在式：“改变”而不是“改变”或“改变”身体应该包括
改变动机，并与以前的行为进行对比。
页脚页脚应该包含任何关于重大更改的信息，也是引用GitHub问题的地方
提交closures 。
这里有一个详细的描述。
例：
修复（ngOptions）：ngModel是可选的
我的5美分，下面的链接是混帐，但无论如何，可以certificate是有用的：
http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
基本的东西（根据那篇文章）是先写一个简短的描述（50个字符），然后你可以详细说明更多的东西，始终保持less于72个字符宽度。
- Bug ID :(如果适用）
- 更改说明：
- 代码评论：
- testing单位：
- 目标发布标签：
我经常做的一件事情是：如果更改是由某种错误/跟踪器软件触发的，那么以一致的方式包含错误ID。 这样，跟踪后期所有与错误相关的更改变得更加容易。
例：
BugID：2345添加了用户input的validation以避免利用。
我们使用Altassian JIRA作为bug跟踪器，Subversion使用我们的源代码控制–JIRA有一个很好的function，可以跟踪与该bug相关的提交，并将其放入到bugparsing历史logging中。
因此，我们通常采取的格式是：
PROJECTCODE – 1234：对所做更改进行合理的详细描述
通过“合理详细”我的意思是说，你不只是把“固定的错误”或“改变的实现”，你通常放在一个不是很具体的描述错误仍然告诉实际做了什么，例如，“sorting策略SortingMethod（）从冒泡sorting改为快速sorting以提高性能“。
我们在每个注释行的前面添加一个+或 – 符号，以表明它是否应该包含在发布更改列表中。 然后可以从我们的版本控制日志中自动生成更改列表（或至less第一个草案）。
除此之外，我们还有一个关键字（从有限集合中select）来指示提交的types（错误修复，新特性，整洁等），然后用一个简短的评论来描述这个变化，并附有问题跟踪系统的链接。
[+/-][Keyword]: [Description]
一般的格式可以用一个提交钩子强制执行，但是描述仍然需要经过人工validation，以确保每个人都提交有用的提交信息。
我们并不关心自由文本，但是每个人都需要input提交所属任务的错误跟踪标签ID，以及同行对他的代码进行审查。
第一个可能会产生一些快速修复的开销，但它可以是一个生命的救星。 每一行代码的实际原因都非常有价值。
第二个只是鼓励做同行评议。
我认为错误ID（如果有的话）是一个好主意。
我最喜欢的一个关于FogBugz的特性之一就是你可以设置一个钩子脚本，当你在提交日志中inputbug ID时，提交信息被添加到FogBugz的情况下。 
图像来自这里
除此之外，只要写一些有意义的话来说明你为什么做了你所做的改变。
考虑遵循git本身遵循的准则： http : //git.kernel.org/cgit/git/git.git/tree/Documentation/SubmittingPatches? id= HEAD
尤其是：
（2）很好地描述你的改变。
提交消息的第一行应该是一个简短的描述（50个字符是软限制，参见git-commit（1）中的讨论），并且应该跳过句号。 在大多数情况下，通常在第一行的前面添加“区域”，其中区域是被修改的代码的一般区域的文件名或标识符，例如
。 归档：ustar头校验和计算无符号
。 git-cherry-pick.txt：阐明修订范围表示法的使用
如果不确定要使用哪个标识符，请对正在修改的文件运行“git log –no-merges”来查看当前约定。
机构应该提供一个有意义的提交信息，其中：
。 解释了变化试图解决的问题，现在的代码没有改变，怎么了。
。 certificate变化解决问题的方式，嗨，为什么变化的结果更好。
。 如果有的话，考虑但丢弃替代解决scheme。
描述你在命令式的情绪上的变化，比如“make xyzzy do frotz”，而不是“这个补丁让xyzzy做frotz”或者“我改变了xyzzy做frotz”，就好像你正在命令代码库改变它行为。 尽量确保你的解释可以在没有外部资源的情况下被理解。 总结讨论的相关要点，而不是给邮件列表存档一个URL。
如果提交信息的第一行似乎是不言自明的，那么在我看来，我将主体留空。
我觉得很难得到正确的提交信息。 为什么不build议这样做：
每个提交消息必须以由提交解决的Bug /任务ID开始。 还有什么是喋喋不休的…
我首选的提交消息格式是基于Chris Beams 撰写的“如何撰写提交信息”以及Joel Parker Henderson的“主动动词”以及我自己的一些想法：
- 用问题标识引导。 这使得查看相关案例编号变得容易，而不需要search提交消息的主体。
- 从最终用户的angular度解释正在解决的问题 （如果适用）。 这部分应该是一个非技术性，简明，高层次的概述。 这可能在问题跟踪系统中有些重复的内容，但没关系。 在审查提交历史logging时，我不希望在跟踪系统中打开问题来了解每个提交的基础知识。
- 是什么从发展的angular度来看它。 有人不小心通过复制/粘贴引入不良的逻辑？ 查看提交历史logging以查看发生了什么。 如果你只是不知道是什么原因造成的，那很好 – 写道：“我不知道为什么这会被打破。” 至less下一个开发者会知道你只是在猜测。
- 为什么这个改变修复了它 。 为什么新代码比旧代码更正确？ 如果你不能确定为什么旧的代码是错的，是什么让你认为新的代码是正确的？
格式：
IssueID: Short description (starting with one of the "active verbs") Concise overview of problem (ideally from the end-user perspective). Caused by (technical reasons go here). Fixed by (technical fix explanation goes here).
例：
995: Fix JS error on landing page preventing sign-in It wasn't possible to sign in on the landing page because the email and password inputs were not being displayed. Caused by invalid logic accidentally introduced by #994 which assumed that the user was already signed in, thus attempting to render the welcome message with the user's name (which isn't yet accessible since they're not signed in). Fixed by changing the logic to check if the user is already signed in before attempting to render the welcome message.
在上面的例子中，你应该能够知道问题是什么，它是如何得到的，为什么我认为这些改变是解决问题的正确方法。 你甚至不需要看代码来理解改变了什么，为什么。
对于微不足道的改变，忽略提交体（甚至是问题编号，如果改变与任何跟踪的问题无关）是完全正确的。
例子：
Cut old dead code Document User.setAddress Refactor User.getName for readability 564: Add missing name to profile page Bump lodash to latest version
