创建拉取请求¶

本章描述了维护者如何创建并向其他维护者提交拉取请求。这对于将更改从一个维护者的代码树转移到另一个维护者的代码树非常有用。

本文档由 Tobin C. Harding（当时他并非经验丰富的维护者）主要根据 Greg Kroah-Hartman 和 Linus Torvalds 在 LKML 上的评论撰写。Jonathan Corbet 和 Mauro Carvalho Chehab 提供了建议和修正。如有不准确之处，并非有意，但实属难免，请将任何指责发送至 Tobin C. Harding <me@tobin.cc>。

原始邮件讨论串

https://lore.kernel.org/r/20171114110500.GA21175@kroah.com

创建分支¶

首先，你需要将所有希望包含在拉取请求中的更改放在一个独立的分支上。通常，你会将此分支基于你打算发送拉取请求的开发者的代码树中的一个分支。

为了创建拉取请求，你必须首先为你刚刚创建的分支打上标签。建议你选择一个有意义的标签名称，以便你和他人即使在一段时间后也能理解。一个好的做法是在名称中包含原始子系统和目标内核版本的指示符。

Greg 提供了以下建议。一个包含针对 drivers/char 杂项内容的拉取请求，若要应用于内核版本 4.15-rc1，可以命名为 char-misc-4.15-rc1。如果该标签是从名为 char-misc-next 的分支生成的，你将使用以下命令：

git tag -s char-misc-4.15-rc1 char-misc-next

这将创建一个名为 char-misc-4.15-rc1 的已签名标签，它基于 char-misc-next 分支的最新提交，并使用你的 GPG 密钥进行签名（请参阅配置 Git）。

Linus 只接受基于已签名标签的拉取请求。其他维护者可能有所不同。

当你运行上述命令时，git 会将你带入一个编辑器，并要求你描述该标签。在这种情况下，你正在描述一个拉取请求，因此请概述其中包含的内容、为何应合并它以及（如果有的话）进行了哪些测试。所有这些信息最终都将包含在标签本身中，然后维护者在合并拉取请求时会将其放入合并提交中。因此请仔细撰写，因为它将永远存在于内核代码树中。

正如 Linus 所说：

Anyway, at least to me, the important part is the *message*. I want
to understand what I'm pulling, and why I should pull it. I also
want to use that message as the message for the merge, so it should
not just make sense to me, but make sense as a historical record
too.

Note that if there is something odd about the pull request, that
should very much be in the explanation. If you're touching files
that you don't maintain, explain _why_. I will see it in the
diffstat anyway, and if you didn't mention it, I'll just be extra
suspicious.  And when you send me new stuff after the merge window
(or even bug-fixes, but ones that look scary), explain not just
what they do and why they do it, but explain the _timing_. What
happened that this didn't go through the merge window..

I will take both what you write in the email pull request _and_ in
the signed tag, so depending on your workflow, you can either
describe your work in the signed tag (which will also automatically
make it into the pull request email), or you can make the signed
tag just a placeholder with nothing interesting in it, and describe
the work later when you actually send me the pull request.

And yes, I will edit the message. Partly because I tend to do just
trivial formatting (the whole indentation and quoting etc), but
partly because part of the message may make sense for me at pull
time (describing the conflicts and your personal issues for sending
it right now), but may not make sense in the context of a merge
commit message, so I will try to make it all make sense. I will
also fix any speeling mistaeks and bad grammar I notice,
particularly for non-native speakers (but also for native ones
;^). But I may miss some, or even add some.

                Linus

Greg 给出了一个拉取请求示例：

Char/Misc patches for 4.15-rc1

Here is the big char/misc patch set for the 4.15-rc1 merge window.
Contained in here is the normal set of new functions added to all
of these crazy drivers, as well as the following brand new
subsystems:
        - time_travel_controller: Finally a set of drivers for the
          latest time travel bus architecture that provides i/o to
          the CPU before it asked for it, allowing uninterrupted
          processing
        - relativity_shifters: due to the affect that the
          time_travel_controllers have on the overall system, there
          was a need for a new set of relativity shifter drivers to
          accommodate the newly formed black holes that would
          threaten to suck CPUs into them.  This subsystem handles
          this in a way to successfully neutralize the problems.
          There is a Kconfig option to force these to be enabled
          when needed, so problems should not occur.

All of these patches have been successfully tested in the latest
linux-next releases, and the original problems that it found have
all been resolved (apologies to anyone living near Canberra for the
lack of the Kconfig options in the earlier versions of the
linux-next tree creations.)

Signed-off-by: Your-name-here <your_email@domain>

标签消息的格式与 Git 提交 ID 类似。顶部有一行为“摘要主题”，底部务必签名。

现在你已经有了一个本地的已签名标签，你需要将其推送到可以被检索的地方：

git push origin char-misc-4.15-rc1