这篇向导专为那些希望在该软件上做出贡献的程序员而写。
（0）决定你工作的基石是什么。
一般而言，应该基于和你的修改相关的最旧的版本分支上。
-如果你是要修复一个 bug，则通常基于‘maint’版本。
如果该 bug不在 ‘maint’中出现，那么就应该基于‘master’。如果那个 bug 也不存在于‘master’中的话，你就应该去找介绍该 regression的专题，然后应该在该主题的指引下进行。
- 如果情况特殊，新特性应该建立在‘master’上。如果新特性是依赖于 ‘pu’而不是 ‘master’，那应该在该专题的指引下进行。
- 如果修正和改善一个没有出现在‘master’上的专题，那么你应该在该专题的相关指引下进行。如果该专题还没有被 merge 到 ‘next’，请添加一个指引，然后把细小的修正挤压到一个系列中。
-针对一个新的特性是基于一系列不在‘master’中的专题这种异常情况，要在‘next’或‘pu’上进行独立的工作，同时分发修补程序以进行讨论。在最后的合并之前，你可能需要等待一段时间，直到部分相关的专题已摆脱了“master”（graduate to ‘master’），之后再重新定位工作所依赖的基石。
-系统的某些模块可能由专门的维护人员在他们自己的仓库中进行维护（参考下面关于“Subsystems”的部分）.在这些模块上进行修改需要基于他们的代码提交树。
若要查找一个专题分支的指引，运行"git log–first-parent master..pu"然后查找合并信息。该提交的第二个父节点就是该专题的分支指引。
（1）分别提交逻辑上不相关的修改
除非你的修改真的非常非常重要，否则不要发送在你的工作树和提交头之间所生成的修改。取而代之的是，总是提交拥有完整提交信息的修改文件及从你自己的仓库中生成一系列的修改文件。相信我，这是一个美好的原则。
为你的修改提供足够详细的说明，使别人可以通过它来判断你的修改是否有价值，而不用通过阅读你提交的修改文件来判断你提交的代码在多大程度上和你的说明所承诺的一致。
如果你开始的描述非常的长，那应该敲响你的警钟，你可能需要把你的提交分成更好的模块。
话虽这么说，但如果你的补丁有一份简洁的描述同时能够帮助审阅者审阅你的修改，帮助未来的维护人员理解你的代码，那将是最美丽的补丁。
包括以下的描述也是一件值得的事：
1、 准确概括这个科目的重点、核心。
2、 描述修改的目的。
3、 该修改使用的方法。
4、 如果相关，当前修改与前一版本的本质区别是什么
确保你测试debug过你修改的文件。参考 t/README
当添加一个新的特性的时候，请确保你测试过你的代码，表明它只做了它该做的，不多也不少。此外，还需要保证你的测试套件在你提交后能够通过检查。可别忘记更新你的文档以记录你的提交行为。
提到文档的问题，那就不得不提由于英国英语和美国英语在拼写和语法形式上存在的文化差异所导致的混淆。在某种程度上，这真是件糟糕的事情。只是为了更正这两者之间的不一致性而创造一个庞大的包罗所有文件的补丁也是不值得提倡的，也很难做到。
冒着带来其它的连锁反应及潜在冲突的险而做这个修改也是不值得的。
我们更喜欢在它们（不一致性）附近做一些其它的真正工作时，以副作用的形式通过一些小的容易理解的补丁渐进地修改这两者的不一致性，使其倾向于美国英语。
（比如：修改 en_UK 检查为en_US 检查，然后为了更清晰而修改一个段落）。显然，进行拼写错误检查会更受欢迎（"teh->"the"），更适宜的是与其它的文档修改分开，作为一个独立的修改而提交。
哦，差点忘记了另外一件大事了。我们对于空白字符非常挑剔。请确保你的修改不会引发错误：with the sample pre-commit hook shipped intemplates/hooks--pre-commit.（不懂）为了保证不会出现上述错误，请在你提交之前执行 git diff --check
（2）更好地描述你的修改。
提交信息的第一行应该是一个简短的描述（一般限制在50个字符内，请参考 git-commit(1)中的DISCUSSION部分），应该跳过句号。
多数情况下，在第一行的前面添加“area：”域，其中“area:”表示的是被修改代码所在的主要区域的文件名或其标识符。比如：
.archive: ustar header checksum is computed unsigned
.git-cherry-pick.txt: clarify the use of revision range notation
如果你不确定使用哪个标识符，在你所修改的文件上执行"git log --no-merges"以查看当前使用的约定。
剩下的主体部分应该提供一个有意义的提交信息，包括：
解释当前修改尝试修正的问题，换句话说，原有代码哪里做的不好？
证明你的修改能够解决上面提到的问题，换句话说，为什么你的修改是值得的？
用祈使语气描述你的修改(比如应该描述成"make xyzzy do frotz" 而不是"[Thispatch] makes xyzzy do frotz" or "[I] changed xyzzyto do frotz")，就好像你对代码发号施令，要求其修改自己的行为。
尽量使理解你的程序不需要额外的资源。不是给出一个到概括了当前讨论相关问题的文件列表的链接。
(3)使用 Git 工具生成你提交的补丁。
Git 依据“diff”工具生成最受欢迎的 unidiff 格式。即使你的修改涉及到文件重命名，也不需要害怕在"git diff" 或
"git format-patch" 中使用 –M 选项。接收者有能力处理它们。
请确保你提交的修改不包含被注释掉的调试代码，也不应包含额外的、与当前修改目的无关的文件。
保险起见，请在生成补丁后进行检查。在发送之前，请确保它已被应用在“master“分支头上。如果你正准备在它的“next”分支上工作，那很好，否则也请你这么认为。（保证你足够认真对待这件事）
（4）发送补丁
在 git 邮件列表中的成员应该能够阅读和评论你提交的修改。开发者能够使用标准电子邮件工具应用你的修改是很重要的。因为他们可能针对你代码的某一特别部分进行评论。为此，每一个修改都应该用分离的信息进行“在线”提交。
多个相关的修改应该集成在他们独自的邮件列表中，以使读者能够找到该系列的所有相关部分。为此，像回应一样，给他们发送第一个修改的额外“附信”消息（参考下面）或各自修改的前置修改。
如果你的日志消息（包括你在线上签署的名字）不能够用 ASCII表示，请确保你发送了一份正确编码的信。
警告：当心你邮件代理的自动换行弄乱你的代码。不要剪切粘贴你的代码。一不留神就会丢失代码的 tap 字符。
一个惯用法是在你的主题行前面加上[PATCH]。这样让别人更容易区分这是一个修改还是其他的邮件讨论。流行做法是在 patch 后面使用额外的标记及用方括号把这些标记括起来。比如，一般用 [PATCH/RFC]表示当前修改还不能被应用，仅作讨论。[PATCH V2],[PATCH V3]等一般表明当前发送的是之前修改的更新版本。
在修改的前面应该是你的提交信息，并以如下签署作为结束：空行，然后是三个破折号单独一行，最后是 diffstat 输出的信息和你的修改本身。
如果你是转发别人的修改，你可以在提交信息的前面单独开一行写上"From:"原作者。
你或许希望添加额外的解释而不单单是提交信息本身。把这样的“附信”信息写在那三个破折号所在行和 diffstat 信息之间。至于那些需要多次循环查看和讨论的修改，每一次改变所做的解释可以被保存在git-notes 中，可以通过命令`git format-patch --notes`被自动地插入在那三个破折号后面。
不要添加 MIME 附件，无论压缩与否。不要让你的电子邮件客户端发送QP编码。不要让你的电子邮件客户端发送可以破坏修改中空白的format=flowed 等形式的内容。
由于很多主流的电子邮件应用程序并不总是把 MIME 转换成纯文本，所以禁止在你的代码上做评论。MIME 附件也使得处理时间增长。添加 MIME 附件并不会增加修改被接收的可能性，但却有可能增加时延。
例外：如果你的寄邮者正在修改补丁那么他可能会要求你重发送一份MIME，这样则没问题。
不要用 PGP 签署你的补丁，至少不是现在。更常见的是，你的维护人员或在邮件列表中的人员没有你的 PGP 密钥，而他们可能会因为麻烦而不去获得该密钥。
对你补丁的评价不会因为你而改变。一个良好的“不明来历”的补丁比一个来自著名的，受尊敬者的但是做的很差的或者做的不正确的补丁更容易被接受。如果你真的真的真的想生成一个 PGP 签名的补丁，以"multipart/signed" 格式化它，而不是以‘-----BEGIN PGP SIGNED MESSAGE-----‘作为开头的纯文本信息。
发送你的补丁，用"To:"设置邮件列表，用"cc:" 列出在这个领域中你接触到的人（来自 "gitblame $path" and "git shortlog --no-merges $path"中的信息可以帮助你识别他们），以征求他们评论和查看。
在当前列表中达到共识之后，说明应用该补丁的时机到了，重新发送，用"To:"列出维护人员[*1*]中的名单，用 "cc:"列出包含在 [*2*]中的名单。
不要忘记添加附注，比如"Acked-by:","Reviewed-by:" 和"Tested-by:" 等，写下必要的人物，以感谢他们对你的帮助。
[地址]
*1*当前维护人员: gitster@pobox.com
*2* 邮件列表: git@vger.kernel.org
(5)为你的工作署名。
为了更好地跟踪谁做了什么，我们借用了linux 内核项目中在邮件讨论中进行讨论的补丁的签证过程。尽管git的核心是一个小得多的项目，但这也是一个不错的原则。
签证是写在你的补丁解释后面的一个小行中，以证明当前补丁是你写的或者你有权利把它作为开源补丁公布。规则非常简单：如果你能证明以下几点：
Origin1.1 开发证书。
在该项目上做贡献，我保证以下：
(a)该贡献完全/部分由我完成，我有权利在遵守开源证书的条件（在文件中指示）下发布之。
(b)该贡献是建立在前人工作上的，就我说知，它遵从了适当的开源证书要求，证书指出（正如文件所提及），在相同开源证书下（除非我被允许在不同证书下提交），我有权利提交那份工作的修改，无论是完全或部分由我个人完成的。或者
(c)该贡献由其它准守(a),(b)或(c)者直接提供给我，我没有进行任何修改。
(d)我明白和同意这个项目及其贡献是公开的，该贡献的记录(包括所有我提交中涉及到的人的信息，也包括我的签署)会被无限期保留，而且这个贡献可能会与这个项目或开原证书涉及到的工作一起重新发布。
然后你只需要添加形如下面的一行文字：
Signed-off-by:Random J Developer <random@developer.example.org>
如果你用–s选项执行git-commit命令，这行文字会被Git自动添加进去。
注意，当你跟从符合上面D-C-O规则的补丁时，可以另起一行添加你自己的 Signed-off-by
同时请注意，要在 Signed-off-by: 中使用真名。
如果你喜欢，你可以在末尾添加额外的标签：
1、"Reported-by:" 表示把发现当前补丁所尝试修复的bug的功劳归功于某个人。
2、"Acked-by:"表示更熟悉该补丁所对应区域的人喜欢该补丁。
3、"Reviewed-by:" 与其它标签不一样，该标签只能由审阅者提供，而且表示她完全同意把该补丁的布置在应用上。通常是在详细审阅后才会使用。
4、"Tested-by:" 表示这个人使用过该补丁，而且发现它产生了期望的效果。
你也可以创建自己的标签或者使用流行的，比如："Thanks-to:","Based-on-patch-by:", or "Mentored-by:".等。
------------------------------------------------
有自己专用维护人员的子系统
系统的某些部分有自己专用的维护人员，他们使用自己的仓库。
-git-gui/ comes from git-gui project, maintained by Pat Thoyts:
git://repo.or.cz/git-gui.git
-gitk-git/ comes from Paul Mackerras‘s gitk project:
git://ozlabs.org/~paulus/gitk
- po/comes from the localization coordinator, Jiang Xin:
https://github.com/git-l10n/git-po/
（上面的就不翻译了）
上面那些部分的补丁应该基于他们自己的版本树。
------------------------------------------------
理想的补丁流程：
下面是这个项目现在的维护人员给贡献者提供的关于理想补丁流的建议
(0)你提出的不足，自己编码解决。
(1)把它发送给list和cc上可能需要知道当前改变的人。
你在拿谁的代码开到，谁就可能是需要知道的人。这些人最有可能是那些有足够知识，能够为你提供帮助的人，但他们并没有这个义务(比如：你可以请求他们提供帮助，但是不要命令)。"git log -p -- $area_you_are_modifying" 或许会帮你找出他们。
(2)获得评价和建议进行发展。你甚至可能以补丁的补丁的形式获得它们。
(3) 润色，精炼你的修改然后重发给列表上的和那些愿意花费时间改善你补丁的人。返回第二步。
(4)最好是在最后一轮，列表上的人达成共识。把它发给维护人员和抄送列表中的人员。
在该补丁的影响下，一个新的主题分支被创建并被合并到“next”，酝酿一段时间，最后成为‘master’。
为了那些以他做乐子的人不用收集和应用该补丁到自己的树中，在(2)-(3)循环的任何时候，维护人员可以从列表中收集它们然后排序放进‘pu’中。
------------------------------------------------
提交后要清楚补丁所处的状态。
* 你可以利用 Git 本身找出你的补丁什么时候被合并到 master 中。‘git pull --rebase‘会自动跳过已经被使用的补丁，并让你知道上述问题的答案。但它只在你重新定位于你补丁合并后的分支最顶端时才起作用。（比如：如果你的补丁被合并在pu中，但是你却定位在master的顶端，那么上述命令将不起作用）。
*阅读Git 的邮件列表，因为维护人员经常发送命名为"What‘s cookingin git.git" 和 "What‘s in git.git"等邮件通知多种被提议的修改的状态。
------------------------------------------------
给MUA（邮件客户端用户代理）的具体提议：
我收到或从邮件列表中收集的部分补丁存在相同的亏损模式。
参考DISUSSION中 git-format-patch(1)部分，知道你可以把补丁用邮件发给自己并使用git-am(1)来检查你的补丁。
当你做到了，装上你的补丁并试运行之，检查提交日志。如果你的提交日志中出现了你不希望出现的，那么在提交补丁时，维护人员很可能会手工编辑日志信息。如果你想把类似“这是我的第一个补丁”等信息写在补丁邮件中，那应该放在表示提交信息结束的三个破折号行后面
Pine
----
（估计是一个邮件代理客户端）
(Johannes Schindelin)
我不知道还有多少人还在使用 Pine，但是对于那些可怜的灵魂来说，告诉他们最新版本需要 quell-flowed-text 可能是一件好事。
当然也包括"no-strip-whitespace-before-send"选项。据我所知在 4.60版本中有介绍。
(Linus Torvalds)
4.58至少需要这个。
---
diff-tree8326dd8350be64ac7fc805f6563a1d61ad10d32c (frome886a61f76edf5410573e92e38ce22974f9c40f1)
Author: Linus Torvalds<torvalds@g5.osdl.org>
Date: Mon Aug 15 17:23:51 2005 -0700
Fixpine whitespace-corruption bug
There‘s no excuse for unconditionally removing whitespace from the picobuffers on close.
diff --git a/pico/pico.c b/pico/pico.c
--- a/pico/pico.c
+++ b/pico/pico.c
@@ -219,7 +219,9 @@ PICO *pm;
switch(pico_all_done){ /* prepare for/handlefinal events */
case COMP_EXIT : /*already confirmed */
packheader();
#if 0
stripwhitespace();
#endif
c |= COMP_EXIT;
break;
(Daniel Barkalow)
> 提交补丁的补丁，为使用Pine 4.63用户提供的
> 具体MUA帮助章节表示衷心感谢
嗯，好像新版本改变了运行良好时的默认行为以及颠覆了配置选项给人的感觉。(Eitherthator Gentoo 做的。)除非你的原有选项是"strip-whitespace-before-send"(表明你应该避免在提交时进行检查)否则你应该设置选项为 "no-strip-whitespace-before-send"
Thunderbird, KMail, GMail
-------------------------
参考git-format-patch(1)的 MUA-SPECIFIC HINTS 部分。
Gnus
----
可以用在 *Summary* 缓冲中的‘|’传输当前的信息到外部程序，这是使用 "git am" 的简便形式。
然而，如果信息是用 MIME 编码的，那么被传输到程序中的信息将是你在*Article* 缓冲中看到的解码后的内容。
你不希望这种转换的两个常见原因。它可能吞掉非 ASCII 字符（最值得关注的是人们的名字）和空白字符（补丁中的致命一击）。在使用 ‘|’执行管道之前，运行‘C-u g’可以使消息以原始的形式传输，这样就可以解决上述问题了。
原文地址：http://blog.csdn.net/feitianhu213/article/details/44339747
