Commit Policy/zh

简体中文 English

提交策略(Commit Policy)

规则(The Rules)

这是创建或者向Qt的任何共享的仓库中推送 commit 的一般规则。在Qt中和通常一样，这些规则都不是一成不变的，但如果你无正当理由地违反它，你 将会 遭受到公众的嘲笑或凌辱。

1. . 如果你添加了新的函数或类：
   ## 确保每一个都被文档化(fix me)
   ## 遵循 Api 设计原则。与其他的Qt开发者讨论并验证函数和类的名字(进行API审查)。
   # 所有的代码应当遵循 编码惯例。
   # 对于GUI代码，遵循 "风格指导":http://developer.kde.org/documentation/standards/kde/style/basics/index.html (恩，没错是KDE 的)， "Qt Creator翻译提示":http://developer.qt.nokia.com/wiki/Qt_Creator_Translation_Page 并且避免 "国际化错误":http://techbase.kde.org/Development/Tutorials/Localization/i18n_Mistakes.
   # 确保你的修改在所有平台下可以编译和工作。
   # 核实单元测试中没有任何失效 (更多信息见 Qt 自动测试环境)。
   # 为你修复的bug或添加的功能编写新的单元测试。
   # 确保你新加或修改的代码符合 Qt 编码风格。
   # 生成易于审查并有助于产生可读、可搜索、可标注与摘录的历史的 commit 。这有一些提示：
   ## 使用最小的或原子 commit。这意味着每一个commit应当包含一 独立的修改 —— 不混杂无关的修改，且不生成不一致的状态。永远不再在一个较大的 commit 中"隐藏" 无关的修复(fixes)。只在发生功能性代码修改的行中修复编码风格，并且只修复与本次代码修改有关的注释——其他的应该放于单独的 commit 中。
   ## 编写描述性的 commit 消息。使它们自包含，这样人们不需要搜索历史上下文即可明白它。反之，不要将无关的细节放入其中。告诉别人你 为什么 修改一些东西除非它是完全不言而喻的。使用 "Qt commit 模板":http://qt.gitorious.org/qt/qt/blobs/697e236c096d62137fdd155f5ef8d72a26b8636b/.commit-template: 遵循 摘要 + 描述信息 的风格 并且使用伪头部(pseudo-headers) 来引用 JIRA 问题和评论等 并考虑 "Git commit 消息的一般准则":http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html.
   ## 经常Commit。大量使用 <code&gt;git gui&lt;/code&gt; 和 <code&gt;git rebase -i&lt;/code&gt; 来塑造你的历史记录。
   ## 避免不必要的合并(merge)。使用 <code&gt;git pull —rebase&lt;/code&gt; 除非你有未推送的 "正当的&quot; 合并(merge)。
   # 在发布之前找一个了解这些代码的人来审查。如果尚没有候选者，引进他人到你的代码。注意推送到你自己的仓库克隆并 不 被认为是发布，但这是一个请求审查或者工作中进行备份的很有效的方法
   # 不要 commit 任何你不理解的东西。&quot;不知怎么突然工作&quot; 是不可接受的。还原(revert)它如果一个修复(fix)可能被认为有缺陷。 ;)
   # 在推送之前审查你的代码。&lt;code&gt;git log —stat&lt;/code&gt;, <code&gt;git log p&lt;/code&gt; 和 <code&gt;gitk&lt;/code&gt; 是你的朋友。
   # 不要与 git 的预接收钩子(pre-receive hooks)抗争。见下面。
   # 最重要的：点击 <code&gt;<enter&gt;</code&gt; 前动动你的脑子。

h2. 预接收钩子(The pre-receive Hooks)
我们内部的 git 仓库安装有各种的预接收钩子来确保最低限度的质量标准和法律安全。这些&quot;消毒&quot;脚本（不含保密检查）可从 "devscripts软件包仓库&quot;:https://qt.gitorious.org/qt-labs/devscripts 获取。这些检查是：
# 私密检查。 It tries to ensure that no real names are published without explicit consent. A side effect is that it will complain about invalid committer information, which is Good ™. Valid addresses from external contributors are added to a whitelist; that process is semi-automated.
# 行结束符检查。We are developing in a heterogeneous environment with both Unix and Windows machines. Therefore it is imperative to have all files in the repository in the canonical LF-only format. Windows users need to set the git option <code&gt;core.autocrlf&lt;/code&gt; to <code&gt;true&lt;/code&gt; to automatically get CRLF line endings which are suitable for the native tools.
# 冲突标记检查。Unless you are adding a text file which contains the patterns on purpose, you most probably botched a merge/rebase.
# 中间产物文件检查。Generated file check. Don't commit generated files they bloat the repository and create spurious changes. If a file is generated but you don't know how to automate the build process, ask an expert.
# 对外部构建系统的工程或配置文件检查。As we are using qmake, these will in most cases fall under the "generated file&quot; rule anyway.
# 对大文件增添的检查。Think three times whether you really' need that huge media file, test binary or screenshot. As we are using git, such mistakes are not correctable - once you added a huge file, everyone who clones the repository will have to pay for it with network traffic and disk space for all times. Source code files are exempt from the check at all; for the rest it is a bit paranoid (it will complain about anything bigger than 50 KiB or an instantaneous file growth over 150% if the file is bigger than 20 KiB).
# 对超大文件增添的检查。If you trigger that one, you almost certainly did something wrong.
# 对工作过程中推送的检查。This is meant to avoid that you accidentally push something you marked for later cleanup. It checks for the strings "WIP&quot; and "'*" in the summary line and for an empty Reviewed-by line. This check is disabled in the local post-commit hook for obvious reasons.
# 空白与非空白修改混合的检查。A commit may contain only whitespace changes or "proper&quot; changes (with whitespace cleanups only on already changed lines, and, as an exception, additions and removals of empty lines). This helps to ensure the usefulness of <code&gt;git blame&lt;/code&gt; (note that a clean history is better than using <code&gt;git blame w&lt;/code&gt;, as the latter will also hide significant whitespace changes). (currently advisory only)
# 一些简单的代码风格的检查 (currently advisory only)
The checks can be overridden on a case by case basis when needed. Don't even think about overriding any of them unless you have a really good reason. "I need to get this done now" is not a valid reason. Neither is "I cannot be bothered to understand what it wants from me&quot;. If there is any doubt, discuss alternatives with somebody appropriate.
Each error/warning message mentions the key needed to override it. Note that there is only one key per entire category, so make sure to check all reports before you apply the override.
The recommended override command is printed by the hook itself. Don't export the environment variable in the current shell, as you will inevitably forget to unset it again and thus disarm the hooks semi-permanently.
For the overrides to work, you need to tell ssh to forward the GIT_PUSH environment variable to the git server. If you don't have an ssh config file yet, create one. It is probably wise to put a <code&gt;Host scm.dev*</code&gt; line in front of the <code&gt;SendEnv&lt;/code&gt; line to restrict the scope of the setting. Under Windows, the file will be usually located in <code&gt;"C:and Settingslt;user&gt;sh\config&quot;</code&gt;, though apparently it is possible to set HOME like under Unix to change ssh's behavior.
It is possible to run most of the checks locally before attempting to push this is especially useful for the checks which are currently advisory only. See the <code&gt;devtools/shell/git_post_commit_hook&lt;/code&gt; script (it contains installation instructions).