doc: add guide for backporting prs

This guide should help answer questions for contributors
that are not familiar with the backport process.

PR-URL: https://github.com/nodejs/node/pull/11099
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

1 files changed, 92 insertions, 0 deletions

diff --git a/doc/guides/backporting-to-release-lines.md b/doc/guides/backporting-to-release-lines.md
new file mode 100644
index 0000000000..e7e51eb32f
--- /dev/null
+++ b/doc/guides/backporting-to-release-lines.md
@@ -0,0 +1,92 @@
+# How to Backport a Pull Request to a Release Line
+
+## Staging branches
+
+Each release line has a staging branch that the releaser will use as a scratch
+pad while preparing a release. The branch name is formatted as follows:
+`vN.x-staging` where `N` is the major release number.
+
+### Active staging branches
+
+| Release Line | Staging Branch |
+| ------------ | -------------- |
+| `v7.x`       | `v7.x-staging` |
+| `v6.x`       | `v6.x-staging` |
+| `v4.x`       | `v4.x-staging` |
+
+## What needs to be backported?
+
+If a cherry-pick from master does not land cleanly on a staging branch, the
+releaser will mark the pull request with a particular label for that release
+line, specifying to our tooling that this pull request should not be included.
+The releaser will then add a comment that a backport is needed.
+
+## What can be backported?
+
+The "Current" release line is much more lenient than the LTS release lines in
+what can be landed. Our LTS release lines (v4.x and v6.x as of March 2017)
+require that commits mature in a Current release for at least 2 weeks before
+they can be landed on staging. If the commit can not be cherry-picked from
+master a manual backport will need to be submitted. Please see the [LTS Plan][]
+for more information. After that time, if the commit can be cherry-picked
+cleanly from master, then nothing needs to be done. If not, a backport pull
+request will need to be submitted.
+
+## How to submit a backport pull request
+
+For these steps, let's assume that a backport is needed for the v7.x release
+line. All commands will use the v7.x-staging branch as the target branch.
+In order to submit a backport pull request to another branch, simply replace
+that with the staging branch for the targeted release line.
+
+* Checkout the staging branch for the targeted release line
+* Make sure that the local staging branch is up to date with the remote
+* Create a new branch off of the staging branch
+
+```shell
+# Assuming your fork of Node.js is checked out in $NODE_DIR,
+# the origin remote points to your fork, and the upstream remote points
+# to git://github.com/nodejs/node
+cd $NODE_DIR
+# Fails if you already have a v7.x-staging
+git branch v7.x-staging upstream/v7.x-staging
+git checkout v7.x-staging
+git reset --hard upstream/v7.x-staging
+# We want to backport pr #10157
+git checkout -b backport-10157-to-v7.x
+```
+
+* After creating the branch, apply the changes to the branch. The cherry-pick
+  will likely fail due to conflicts. In that case, you will see something this:
+
+```shell
+# Say the $SHA is 773cdc31ef
+$ git cherry-pick $SHA # Use your commit hash
+error: could not apply 773cdc3... <commit title>
+hint: after resolving the conflicts, mark the corrected paths
+hint: with 'git add <paths>' or 'git rm <paths>'
+hint: and commit the result with 'git commit'
+```
+
+* Make the required changes to remove the conflicts, add the files to the index
+  using `git add`, and then commit the changes. That can be done with
+  `git cherry-pick --continue`.
+* Leave the commit message as is. If you think it should be modified, comment
+  in the Pull Request.
+* Make sure `make -j4 test` passes
+* Push the changes to your fork and open a pull request.
+* Be sure to target the `v7.x-staging` branch in the pull request.
+
+### Helpful Hints
+
+* Please include the backport target in the pull request title in the following
+  format: `(v7.x backport) <commit title>`
+  * Ex. `(v4.x backport) process: improve performance of nextTick`
+* Please check the checkbox labelled "Allow edits from maintainers".
+  This is the easiest way to to avoid constant rebases.
+
+In the event the backport pull request is different than the original,
+the backport pull request should be reviewed the same way a new pull request
+is reviewed.
+
+[LTS Plan]: https://github.com/nodejs/LTS#lts-plan