From f1538557251de5a83d3ae431f025121a3d510ca8 Mon Sep 17 00:00:00 2001 From: Evan Lucas Date: Wed, 1 Feb 2017 05:56:41 -0600 Subject: [PATCH] doc: add guide for backporting prs This guide should help answer questions for contributors that are not familiar with the backport process. --- COLLABORATOR_GUIDE.md | 5 +- doc/guides/backporting-to-release-lines.md | 84 ++++++++++++++++++++++ 2 files changed, 88 insertions(+), 1 deletion(-) create mode 100644 doc/guides/backporting-to-release-lines.md diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 7ac8f49ee09ff0..00d44e4e8c4bc9 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -337,7 +337,8 @@ LTS release. When you send your pull request, consider including information about whether your change is breaking. If you think your patch can be backported, -please feel free to include that information in the PR thread. +please feel free to include that information in the PR thread. For more +information on backporting, please see the [backporting guide][]. Several LTS related issue and PR labels have been provided: @@ -364,3 +365,5 @@ When the LTS working group determines that a new LTS release is required, selected commits will be picked from the staging branch to be included in the release. This process of making a release will be a collaboration between the LTS working group and the Release team. + +[backporting guide]: doc/guides/backporting-to-release-lines.md diff --git a/doc/guides/backporting-to-release-lines.md b/doc/guides/backporting-to-release-lines.md new file mode 100644 index 00000000000000..9f47664055a404 --- /dev/null +++ b/doc/guides/backporting-to-release-lines.md @@ -0,0 +1,84 @@ +# 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? + +When a release is being prepared, the releaser attempts to cherry-pick a +certain set of commits from the master branch to the release staging branch. +The criteria for consideration depends on the target version (Current vs. LTS). +If a cherry-pick does not land cleanly on the 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 (currently v7.x) is much more lenient than the LTS +release lines in what can be landed. Our LTS release lines +(currently v4.x and v6.x) require that commits live in a Current release for at +least 2 weeks before backporting. 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 +git checkout v7.x-staging +git pull -r 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. + +```shell +git cherry-pick $SHA # Use your commit hash +``` + +* The commit message should be as close as possible to the commit message on the + master branch, unless the commit has to be different due to dependencies that + are not present in the targeted release line. +* 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) ` + * Ex. `(v4.x backport) process: improve performance of nextTick` +* Please include the text `Backport of #` in the + pull request description. This will link to the original pull request. + +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. When each commit is landed, the new reviewers and the new PR-URL +should be used. + +[`LTS Plan`]: /~https://github.com/nodejs/LTS#lts-plan