Preparing a Patch Series for the Git Project

_i_-th commit of an _n_-commit series. - Each patch is sent as a reply to an introductory email called the _cover letter_ of the series, prefixed "[PATCH 0/_n_]". - Subsequent iterations of the patch series are labelled "PATCH v2", "PATCH v3", etc. in place of "PATCH". For example, "[PATCH v2 1/3]" would be the first of three patches in the second iteration. Each iteration is sent with a new cover letter (like "[PATCH v2 0/3]" above), itself a reply to the cover letter of the previous iteration (more on that below). NOTE: A single-patch topic is sent with "[PATCH]", "[PATCH v2]", etc. without _i_/_n_ numbering (in the above thread overview, no single-patch topic appears, though). [[cover-letter]] === The cover letter In addition to an email per patch, the Git community also expects your patches to come with a cover letter. This is an important component of change submission as it explains to the community from a high level what you're trying to do, and why, in a way that's more apparent than just looking at your patches. The title of your cover letter should be something which succinctly covers the purpose of your entire topic branch. It's often in the imperative mood, just like our commit message titles. Here is how we'll title our series: --- Add the 'psuh' command --- The body of the cover letter is used to give additional context to reviewers. Be sure to explain anything your patches don't make clear on their own, but remember that since the cover letter is not recorded in the commit history, anything that might be useful to future readers of the repository's history should also be in your commit messages. Here's an example body for `psuh`: ---- Our internal metrics indicate widespread interest in the command git-psuh - that is, many users are trying to use it, but finding it is unavailable, using some unknown workaround instead. The following handful of patches add the psuh command and implement some handy features on top of it. This patchset is part of the MyFirstContribution tutorial and should not be merged. ---- At this point the tutorial diverges, in order to demonstrate two different methods of formatting your patchset and getting it reviewed. The first method to be covered is GitGitGadget, which is useful for those already familiar with GitHub's common pull request workflow. This method requires a GitHub account. The second method to be covered is `git send-email`, which can give slightly more fine-grained control over the emails to be sent. This method requires some setup which can change depending on your system and will not be covered in this tutorial. Regardless of which method you choose, your engagement with reviewers will be the same; the review process will be covered after the sections on GitGitGadget and `git send-email`. [[howto-ggg]] == Sending Patches via GitGitGadget One option for sending patches is to follow a typical pull request workflow and send your patches out via GitGitGadget. GitGitGadget is a tool created by Johannes Schindelin to make life as a Git contributor easier for those used to the GitHub PR workflow. It allows contributors to open pull requests against its mirror of the Git project, and does some magic to turn the PR into a set of emails and send them out for you. It also runs the Git continuous integration suite for you. It's documented at https://gitgitgadget.github.io/. [[create-fork]] === Forking `git/git` on GitHub Before you can send your patch off to be reviewed using GitGitGadget, you will need to fork the Git project and upload your changes. First thing - make sure you have a GitHub account. Head to the https://github.com/git/git[GitHub mirror] and look for the Fork button. Place your fork wherever you deem appropriate and create it. [[upload-to-fork]] === Uploading to Your Own Fork To upload your branch to your own fork, you'll need to add the new fork as a remote. You can use `git remote -v` to show the remotes you have added already. From

This section discusses the process of preparing a patch series for submission to the Git project, including the importance of a cover letter, which explains the purpose and context of the changes. The cover letter should have a succinct title and body that provides additional context to reviewers. The section also introduces two methods for sending patches: GitGitGadget, which is useful for those familiar with GitHub's pull request workflow, and `git send-email`, which provides more fine-grained control over the emails to be sent.