建立拉取請求¶

本章描述了維護者如何建立並向其他維護者提交拉取請求。這對於將更改從一個維護者的程式碼樹轉移到另一個維護者的程式碼樹非常有用。

本文件由 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