From f1538557251de5a83d3ae431f025121a3d510ca8 Mon Sep 17 00:00:00 2001 From: Evan Lucas Date: Wed, 1 Feb 2017 05:56:41 -0600 Subject: [PATCH 01/11] 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 From 837bcb96ee68d3ea8af9f67046da24eb4a359a50 Mon Sep 17 00:00:00 2001 From: Evan Lucas Date: Sat, 4 Feb 2017 09:13:31 -0600 Subject: [PATCH 02/11] fixup! commit message --- doc/guides/backporting-to-release-lines.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/guides/backporting-to-release-lines.md b/doc/guides/backporting-to-release-lines.md index 9f47664055a404..18f15396e61276 100644 --- a/doc/guides/backporting-to-release-lines.md +++ b/doc/guides/backporting-to-release-lines.md @@ -64,7 +64,10 @@ 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. + are not present in the targeted release line. The only exception is that the + metadata from the original commit should be removed. If a backport is + required, it should go through the same review steps as a commit landing + in the master branch. * Push the changes to your fork and open a pull request. * Be sure to target the `v7.x-staging` branch in the pull request. From aa404334dbbec60f7ac5fde6d295613f046f01fc Mon Sep 17 00:00:00 2001 From: Evan Lucas Date: Sat, 4 Feb 2017 09:20:30 -0600 Subject: [PATCH 03/11] fixup! cherry-pick instructions --- doc/guides/backporting-to-release-lines.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/doc/guides/backporting-to-release-lines.md b/doc/guides/backporting-to-release-lines.md index 18f15396e61276..7af6f3f5c16a82 100644 --- a/doc/guides/backporting-to-release-lines.md +++ b/doc/guides/backporting-to-release-lines.md @@ -56,12 +56,20 @@ git pull -r upstream v7.x-staging git checkout -b backport-10157-to-v7.x ``` -* After creating the branch, apply the changes to the branch. +* 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 -git cherry-pick $SHA # Use your commit hash +# Say the $SHA is 773cdc31ef +$ git cherry-pick $SHA # Use your commit hash +error: could not apply 773cdc3... +hint: after resolving the conflicts, mark the corrected paths +hint: with 'git add ' or 'git rm ' +hint: and commit the result with 'git commit' ``` +* Make the required changes to remove the conflicts, and then commit the + changes. That can be done with `git commit`. * 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. The only exception is that the From 444359ca63d0766610e33348f18db822ff87e124 Mon Sep 17 00:00:00 2001 From: Evan Lucas Date: Mon, 13 Feb 2017 08:03:11 -0600 Subject: [PATCH 04/11] fixup add backport metadata line --- doc/guides/backporting-to-release-lines.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/guides/backporting-to-release-lines.md b/doc/guides/backporting-to-release-lines.md index 7af6f3f5c16a82..97a4d5b6588fa2 100644 --- a/doc/guides/backporting-to-release-lines.md +++ b/doc/guides/backporting-to-release-lines.md @@ -78,6 +78,10 @@ hint: and commit the result with 'git commit' in the master branch. * Push the changes to your fork and open a pull request. * Be sure to target the `v7.x-staging` branch in the pull request. +* When landing a backport commit, please include the PR-URL from the original + pull request and add `Backport: ` to the commit metadata. + The `Backport` line should be directly after the `PR-URL` line in the + metadata. ### Helpful Hints From 066e61728b2729562598a8938599854b59721670 Mon Sep 17 00:00:00 2001 From: Evan Lucas Date: Wed, 15 Feb 2017 09:33:11 -0600 Subject: [PATCH 05/11] fixup! add details regarding Backport-of --- doc/guides/backporting-to-release-lines.md | 31 +++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/doc/guides/backporting-to-release-lines.md b/doc/guides/backporting-to-release-lines.md index 97a4d5b6588fa2..f1d416f9147629 100644 --- a/doc/guides/backporting-to-release-lines.md +++ b/doc/guides/backporting-to-release-lines.md @@ -79,9 +79,34 @@ hint: and commit the result with 'git commit' * Push the changes to your fork and open a pull request. * Be sure to target the `v7.x-staging` branch in the pull request. * When landing a backport commit, please include the PR-URL from the original - pull request and add `Backport: ` to the commit metadata. - The `Backport` line should be directly after the `PR-URL` line in the - metadata. + pull request as `Backport-of: `. The `Backport-of` line should + be directly after the `PR-URL` line in the metadata. + +Below are examples of an original commit message and a backport commit message. + +In this example, https://github.com/nodejs/node/pull/1234 is the original pull +request and https://github.com/nodejs/node/pull/5678 is the backport. + +Original: + +``` +lib: make something faster + +Switch to using String#repeat to improve performance. + +PR-URL: https://github.com/nodejs/node/pull/1234 +``` + +Backport: + +``` +lib: make something faster + +Switch to using String#repeat to improve performance. + +PR-URL: https://github.com/nodejs/node/pull/5678 +Backport-of: https://github.com/nodejs/node/pull/1234 +``` ### Helpful Hints From b06d19fbefebb42ae12f063be8dd30f2d22df018 Mon Sep 17 00:00:00 2001 From: Evan Lucas Date: Fri, 17 Feb 2017 06:09:53 -0600 Subject: [PATCH 06/11] fixup! fix lts plan reference --- doc/guides/backporting-to-release-lines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/guides/backporting-to-release-lines.md b/doc/guides/backporting-to-release-lines.md index f1d416f9147629..6d8e1ccff8e3f4 100644 --- a/doc/guides/backporting-to-release-lines.md +++ b/doc/guides/backporting-to-release-lines.md @@ -29,7 +29,7 @@ releaser will then add a comment that a backport is needed. 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 +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. @@ -121,4 +121,4 @@ 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 +[LTS Plan]: https://github.com/nodejs/LTS#lts-plan From 4db2488412f05de2cee69f3752e33c6c51dbad9e Mon Sep 17 00:00:00 2001 From: Evan Lucas Date: Fri, 24 Feb 2017 06:02:57 -0600 Subject: [PATCH 07/11] fixup! remove more releaser info --- doc/guides/backporting-to-release-lines.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/guides/backporting-to-release-lines.md b/doc/guides/backporting-to-release-lines.md index 6d8e1ccff8e3f4..5f48c002ddb285 100644 --- a/doc/guides/backporting-to-release-lines.md +++ b/doc/guides/backporting-to-release-lines.md @@ -1,4 +1,4 @@ -# How to backport a Pull Request to a Release Line +# How to Backport a Pull Request to a Release Line ## Staging branches @@ -16,13 +16,10 @@ pad while preparing a release. The branch name is formatted as follows: ## 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. +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? @@ -68,8 +65,9 @@ hint: with 'git add ' or 'git rm ' hint: and commit the result with 'git commit' ``` -* Make the required changes to remove the conflicts, and then commit the - changes. That can be done 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 commit`. * 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. The only exception is that the @@ -115,6 +113,8 @@ Backport-of: https://github.com/nodejs/node/pull/1234 * 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. +* 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 From 27828903d32993b7db4dbaa5f522d99caa3f2578 Mon Sep 17 00:00:00 2001 From: Evan Lucas Date: Fri, 17 Mar 2017 16:50:30 -0500 Subject: [PATCH 08/11] fixup! more changes --- doc/guides/backporting-to-release-lines.md | 24 +++++++++------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/doc/guides/backporting-to-release-lines.md b/doc/guides/backporting-to-release-lines.md index 5f48c002ddb285..10404fd95b8a84 100644 --- a/doc/guides/backporting-to-release-lines.md +++ b/doc/guides/backporting-to-release-lines.md @@ -23,13 +23,12 @@ 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. +The "Current" release line is much more lenient than the LTS release lines in +what can be landed. Our LTS release lines 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 @@ -47,8 +46,10 @@ that with the staging branch for the targeted release line. # 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 pull -r upstream v7.x-staging +git reset --hard upstream/v7.x-staging # We want to backport pr #10157 git checkout -b backport-10157-to-v7.x ``` @@ -74,11 +75,9 @@ hint: and commit the result with 'git commit' metadata from the original commit should be removed. If a backport is required, it should go through the same review steps as a commit landing in the master branch. +* 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. -* When landing a backport commit, please include the PR-URL from the original - pull request as `Backport-of: `. The `Backport-of` line should - be directly after the `PR-URL` line in the metadata. Below are examples of an original commit message and a backport commit message. @@ -103,7 +102,6 @@ lib: make something faster Switch to using String#repeat to improve performance. PR-URL: https://github.com/nodejs/node/pull/5678 -Backport-of: https://github.com/nodejs/node/pull/1234 ``` ### Helpful Hints @@ -111,8 +109,6 @@ Backport-of: https://github.com/nodejs/node/pull/1234 * 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. * Please check the checkbox labelled "Allow edits from maintainers". This is the easiest way to to avoid constant rebases. From 89e7bfbe173b171d7d32599c4d0a04318014aa6e Mon Sep 17 00:00:00 2001 From: Evan Lucas Date: Fri, 17 Mar 2017 16:57:33 -0500 Subject: [PATCH 09/11] fixup! use cherry-pick --continue and fix wording --- doc/guides/backporting-to-release-lines.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/guides/backporting-to-release-lines.md b/doc/guides/backporting-to-release-lines.md index 10404fd95b8a84..a4696f3c75dde0 100644 --- a/doc/guides/backporting-to-release-lines.md +++ b/doc/guides/backporting-to-release-lines.md @@ -24,8 +24,10 @@ 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 require that commits live in a Current -release for at least 2 weeks before backporting. Please see the [LTS Plan][] +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. @@ -68,7 +70,7 @@ 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 commit`. + `git cherry-pick --continue`. * 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. The only exception is that the From fc434b26c8b473ed6fb3eed83259d206a92e8019 Mon Sep 17 00:00:00 2001 From: Evan Lucas Date: Mon, 27 Mar 2017 15:12:37 -0500 Subject: [PATCH 10/11] fixup! use original PR-URL --- doc/guides/backporting-to-release-lines.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/guides/backporting-to-release-lines.md b/doc/guides/backporting-to-release-lines.md index a4696f3c75dde0..2a0107ca42bf3b 100644 --- a/doc/guides/backporting-to-release-lines.md +++ b/doc/guides/backporting-to-release-lines.md @@ -103,7 +103,7 @@ lib: make something faster Switch to using String#repeat to improve performance. -PR-URL: https://github.com/nodejs/node/pull/5678 +PR-URL: https://github.com/nodejs/node/pull/1234 ``` ### Helpful Hints @@ -116,7 +116,6 @@ PR-URL: https://github.com/nodejs/node/pull/5678 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. +is reviewed. [LTS Plan]: https://github.com/nodejs/LTS#lts-plan From a374208cd7d668e4a4bf282a13e335450edde321 Mon Sep 17 00:00:00 2001 From: Gibson Fahnestock Date: Wed, 12 Apr 2017 19:48:18 +0100 Subject: [PATCH 11/11] squash!: remove commit message changes Following on from discussion in: https://github.com/nodejs/LTS/issues/191 the backport PR should start with the same commit message. Any additions can be made by whoever lands the PR. --- doc/guides/backporting-to-release-lines.md | 33 ++-------------------- 1 file changed, 2 insertions(+), 31 deletions(-) diff --git a/doc/guides/backporting-to-release-lines.md b/doc/guides/backporting-to-release-lines.md index 2a0107ca42bf3b..b25d9b499f6218 100644 --- a/doc/guides/backporting-to-release-lines.md +++ b/doc/guides/backporting-to-release-lines.md @@ -71,41 +71,12 @@ 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`. -* 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. The only exception is that the - metadata from the original commit should be removed. If a backport is - required, it should go through the same review steps as a commit landing - in the master branch. +* 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. -Below are examples of an original commit message and a backport commit message. - -In this example, https://github.com/nodejs/node/pull/1234 is the original pull -request and https://github.com/nodejs/node/pull/5678 is the backport. - -Original: - -``` -lib: make something faster - -Switch to using String#repeat to improve performance. - -PR-URL: https://github.com/nodejs/node/pull/1234 -``` - -Backport: - -``` -lib: make something faster - -Switch to using String#repeat to improve performance. - -PR-URL: https://github.com/nodejs/node/pull/1234 -``` - ### Helpful Hints * Please include the backport target in the pull request title in the following