doc: add triaging for lts releases guide #20165

BethGriggs · 2018-04-20T11:55:29Z

Adds info for backporting commits and PRs to LTS branches.

If we can get a guideline process agreed and written down, it should make it easier for more people to help out with the backporting.

//cc @gibfahn, @MylesBorins

Checklist

documentation is changed or added
commit message follows commit guidelines

vsemozhetbyt · 2018-04-20T13:03:57Z

How does this guide relate to the https://github.com/nodejs/node/blob/master/doc/guides/backporting-to-release-lines.md ?

richardlau · 2018-04-20T13:44:37Z

Are the mechanics of backporting to LTS different from backporting to current?

MylesBorins · 2018-04-20T16:28:07Z

@vsemozhetbyt I'll review both documents and see if there is value in merging them or having different docs... might be good to have a separate one specifically about triaging.

@richardlau backporting to LTS is the same for external collaborators. Triaging and landing commits (backport and from release lines) is different.

BethGriggs · 2018-04-20T16:32:18Z

backporting-to-release-lines currently instructs contributors on how to open a backport PR, whereas this guide would document the process of landing the backport PRs/triaging commits to land. Initially I separated it out as I thought it may be confusing to show how to open a backport commit (applicable to any contributor) in the same place as how to land backport PRs/commits on staging branches (collaborator specific).

Perhaps any additional content should just be merged and expand the COLLABORATOR_GUIDE.md#technical-howto?

The main aim is to make it easier/clearer for any collaborator to traige and pull commits into the staging branches.

BridgeAR · 2018-04-25T11:34:50Z

@nodejs/documentation PTAL

BridgeAR · 2018-04-25T11:35:15Z

@BethGriggs is this still WIP? (Please use the labels for that by the way)

mhdawson · 2018-05-10T14:09:58Z

doc/guides/backport-to-lts-branches.md

@@ -0,0 +1,124 @@
+# How to backport to LTS branches


Should this be called "Creating a release" instead.

+1 to preparing an LTS release or Triaging for LTS releases

Trott · 2018-05-23T16:06:08Z

doc/guides/backport-to-lts-branches.md

+
+# How to backport to the current release
+
+- Run branch-diff to generate a list of shas:


Nit: shas -> SHAs or even SHA checksums or whatever the best word (instead of checksums) might be there (commit hashes?).

BridgeAR · 2018-05-29T19:46:50Z

Closing due to no response. @BethGriggs please feel free to reopen / leave a comment in case you would like to work on this again or open a new PR.

gibfahn · 2018-05-29T20:00:13Z

We really need this.

jasnell · 2018-05-29T22:31:54Z

+1 to reopening... closing this was premature.

BethGriggs · 2018-05-31T10:32:04Z

I have been on vacation - planning to sync up with @MylesBorins this week to progress this guide.

BethGriggs · 2018-06-05T11:32:58Z

@MylesBorins, what do you think should happen to this guide based on discussions at the Berlin summit about a process change (e.g. about utilizing minor and patch branches from @BridgeAR)? Have we written that proposal down anywhere?

gibfahn · 2018-06-05T21:11:00Z

@MylesBorins, what do you think should happen to this guide based on discussions at the Berlin summit about a process change (e.g. about utilizing minor and patch branches from @BridgeAR)?

Not Myles Borins 😁, but my preference would be to document the process as is, and then we can use the PR to update it with the new proposal to discuss how exactly that should work.

MylesBorins

So I've added some comments in line.

I'm curious, this guide mostly breaks down to a handful of git-fu. Perhaps it makes sense to make a separate git guide for core that includes aliases and techniques and focus on how to decide if a commit should land and branch-diff techniques for this guide?

Also open to landing all the things in here, but there is the risk of repeated information

MylesBorins · 2018-06-05T21:50:04Z

doc/guides/backport-to-lts-branches.md

@@ -0,0 +1,124 @@
+# How to backport to LTS branches


+1 to preparing an LTS release or Triaging for LTS releases

MylesBorins · 2018-06-05T21:50:45Z

doc/guides/backport-to-lts-branches.md

+
+- Clone node checkout staging branch
+  ```bash
+  git clone git@github.com/nodejs/node --origin DANGER


can you explain --origin DANGER rather than upstream which is usually the convention I've seen used

That was a suggestion from @gibfahn for my setup - i'll swap it back to upstream so that it is consistent with other docs.

MylesBorins · 2018-06-05T21:50:59Z

doc/guides/backport-to-lts-branches.md

+
+- Make sure up to date with staging
+  ```bash
+  git fetch --all


i usually do git remote update -p

MylesBorins · 2018-06-05T21:52:06Z

doc/guides/backport-to-lts-branches.md

+- Check approvals (you can approve yourself)
+- Check SemVer
+- Check the PR metadata wasn't changed from `master` commit.
+- If there are merge conflicts, comment in the issue asking the PR author to rebase.


alternatively you can fix this manually while landing

MylesBorins · 2018-06-05T21:53:03Z

doc/guides/backport-to-lts-branches.md

+- Land if okay
+  - Add git alias if you haven't already:
+  ```bash
+  git config --global alias.pa '!curl -L $1.patch | git am -3 -S --whitespace=fix #'


I've ended up removing --whitespace=fix as it can cause some serious issues with certain backports.

MylesBorins · 2018-06-05T21:55:03Z

doc/guides/backport-to-lts-branches.md

+  # Add this line to each commit under the PR-URL:
+  # Backport-PR-URL: https://github.com/nodejs/node/pull/12345
+  ```
+  - Test the commit and push it


sometimes I'll just run the tests for the PR in question when backporting rather than running all the tests

see: https://github.com/MylesBorins/dot-files/blob/master/.bash_profile#L64

MylesBorins · 2018-06-05T21:56:26Z

doc/guides/backport-to-lts-branches.md

+
+- Run branch diff /w parameters
+  ```bash
+  branch-diff ???


branch-diff vX.x-staging upstream/vY.x -exclude-label semver-major,semver-minor,dont-land-on-vX.x,backport-requested-vX.x,backported-to-vX.x,baking-for-lts --filter-release

where X = LTS branch and Y = Current branch

MylesBorins · 2018-06-05T21:58:05Z

doc/guides/backport-to-lts-branches.md

+
+- Run branch-diff to generate a list of shas:
+  ```bash
+  branch-diff --reverse --sha


$ branch-diff vX.x-staging upstream/master --exclude-label semver-major,dont-land-on-vX.x,backport-requested-vX.x,backported-to-vX.x --filter-release --format=sha --reverse > commits $ cat commits | xargs git cherry-pick

MylesBorins · 2018-06-05T21:58:33Z

doc/guides/backport-to-lts-branches.md

+- For each commit try to cherry-pick it, if it fails:
+  - Open PR in browser.
+  - Either fix conflicts and backport, or don't fix and bail.
+  - If PR had multiple commits, `git cherry-pick --quit` and `git reset --hard` to


this will only work when doing the above step

codebytere · 2018-08-02T16:06:45Z

doc/guides/triaging-for-lts-releases.md

+    ```
+  - Close the backport PR with `Landed in $(git rev-parse --short HEAD)`, update the label on the original PR from `backport-requested-vX.x` to `backported-to-vX.x`.
+
+### Triage commits


I'd say this should come at the top before the Triage PRs section potentially?

codebytere · 2018-08-02T16:08:41Z

doc/guides/triaging-for-lts-releases.md

+  ```
+  - Patch Pull Request onto staging branch:
+  ```bash
+  git pa https://github.com/nodejs/node/pull/12345


For ease of understanding it might be helpful to add that this patch flow also applies to commits, and add a section to commit triaging that includes an example similar to:
$ git pa https://github.com/nodejs/node/commit/1a2b3c4d

codebytere · 2018-08-02T16:08:56Z

doc/guides/triaging-for-lts-releases.md

+- Land if okay
+  - Add git alias if you haven't already:
+  ```bash
+  git config --global alias.pa '!curl -L $1.patch | git am -3 -S --whitespace=fix #'


nit: remove --whitespace=fix #

richardlau · 2018-12-03T18:11:20Z

doc/releases.md

-appropriate commits into it. To determine the relevant commits, use
+appropriate PRs and commits into it.
+
+Go through PRs with the label `vN.x`. e.g. [PRs with the v8.x label](https://github.com/nodejs/node/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc+label%3Av8.x).


Suggested change

Go through PRs with the label `vN.x`. e.g. [PRs with the v8.x label](https://github.com/nodejs/node/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc+label%3Av8.x).

Go through PRs with the label `vN.x`. e.g. [PRs with the `v8.x` label](https://github.com/nodejs/node/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc+label%3Av8.x).

Trott · 2018-12-04T04:06:35Z

Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/1818/

Add a section on triaging commits and PRs to land in releases.

Trott · 2018-12-05T02:28:44Z

Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/1835/

Trott · 2018-12-05T02:37:06Z

Landed in a845d7a

Add a section on triaging commits and PRs to land in releases. PR-URL: nodejs#20165 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com>

Add a section on triaging commits and PRs to land in releases. PR-URL: #20165 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com>

Add a section on triaging commits and PRs to land in releases. PR-URL: nodejs#20165 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com>

Add a section on triaging commits and PRs to land in releases. PR-URL: #20165 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com>

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Apr 20, 2018

vsemozhetbyt added meta Issues and PRs related to the general management of the project. lts Issues and PRs related to Long Term Support releases. labels Apr 20, 2018

MylesBorins self-assigned this Apr 20, 2018

BridgeAR added the wip Issues and PRs that are still a work in progress. label Apr 25, 2018

mhdawson reviewed May 10, 2018

View reviewed changes

Trott reviewed May 23, 2018

View reviewed changes

BridgeAR closed this May 29, 2018

gibfahn reopened this May 29, 2018

MylesBorins reviewed Jun 5, 2018

View reviewed changes

BethGriggs force-pushed the backporting-guide branch from 01e9436 to 7a82142 Compare June 8, 2018 11:12

BethGriggs changed the title ~~[WIP] doc: add backporting to LTS branches guide~~ [WIP] doc: add triaging for lts releases guide Jun 8, 2018

codebytere reviewed Aug 2, 2018

View reviewed changes

BethGriggs force-pushed the backporting-guide branch 3 times, most recently from c1f78e3 to 3087c7d Compare October 9, 2018 10:36

BethGriggs force-pushed the backporting-guide branch from c81ec9e to 4847890 Compare November 22, 2018 13:14

gireeshpunathil approved these changes Dec 3, 2018

View reviewed changes

BethGriggs force-pushed the backporting-guide branch from 4847890 to f53ed14 Compare December 3, 2018 16:11

richardlau approved these changes Dec 3, 2018

View reviewed changes

BethGriggs force-pushed the backporting-guide branch from f53ed14 to cc7f4c7 Compare December 3, 2018 18:32

BethGriggs and others added 2 commits December 4, 2018 18:27

doc: add triaging section to releases.md

72de921

Add a section on triaging commits and PRs to land in releases.

fixup! doc: add triaging section to releases.md

de7a185

Trott force-pushed the backporting-guide branch from cc7f4c7 to de7a185 Compare December 5, 2018 02:27

Trott added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Dec 5, 2018

Trott closed this Dec 5, 2018

BridgeAR mentioned this pull request Dec 5, 2018

v11.4.0 proposal #24854

Merged

4 tasks

BethGriggs mentioned this pull request Feb 12, 2019

v10.15.3 proposal #26063

Merged

BethGriggs deleted the backporting-guide branch June 11, 2019 18:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: add triaging for lts releases guide #20165

doc: add triaging for lts releases guide #20165

BethGriggs commented Apr 20, 2018 •

edited

Loading

vsemozhetbyt commented Apr 20, 2018 •

edited

Loading

richardlau commented Apr 20, 2018

MylesBorins commented Apr 20, 2018

BethGriggs commented Apr 20, 2018

BridgeAR commented Apr 25, 2018

BridgeAR commented Apr 25, 2018 •

edited

Loading

mhdawson May 10, 2018

MylesBorins Jun 5, 2018

Trott May 23, 2018

BridgeAR commented May 29, 2018

gibfahn commented May 29, 2018

jasnell commented May 29, 2018

BethGriggs commented May 31, 2018

BethGriggs commented Jun 5, 2018

gibfahn commented Jun 5, 2018

MylesBorins left a comment

MylesBorins Jun 5, 2018

MylesBorins Jun 5, 2018

BethGriggs Jun 7, 2018

MylesBorins Jun 5, 2018

MylesBorins Jun 5, 2018

MylesBorins Jun 5, 2018

MylesBorins Jun 5, 2018

MylesBorins Jun 5, 2018

MylesBorins Jun 5, 2018

MylesBorins Jun 5, 2018

codebytere Aug 2, 2018

codebytere Aug 2, 2018

codebytere Aug 2, 2018

richardlau Dec 3, 2018

Trott commented Dec 4, 2018

Trott commented Dec 5, 2018

Trott commented Dec 5, 2018


		# How to backport to the current release

		- Run branch-diff to generate a list of shas:

	Go through PRs with the label `vN.x`. e.g. [PRs with the v8.x label](https://github.com/nodejs/node/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc+label%3Av8.x).
	Go through PRs with the label `vN.x`. e.g. [PRs with the `v8.x` label](https://github.com/nodejs/node/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc+label%3Av8.x).

doc: add triaging for lts releases guide #20165

doc: add triaging for lts releases guide #20165

Conversation

BethGriggs commented Apr 20, 2018 • edited Loading

Checklist

vsemozhetbyt commented Apr 20, 2018 • edited Loading

richardlau commented Apr 20, 2018

MylesBorins commented Apr 20, 2018

BethGriggs commented Apr 20, 2018

BridgeAR commented Apr 25, 2018

BridgeAR commented Apr 25, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BridgeAR commented May 29, 2018

gibfahn commented May 29, 2018

jasnell commented May 29, 2018

BethGriggs commented May 31, 2018

BethGriggs commented Jun 5, 2018

gibfahn commented Jun 5, 2018

MylesBorins left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Trott commented Dec 4, 2018

Trott commented Dec 5, 2018

Trott commented Dec 5, 2018

BethGriggs commented Apr 20, 2018 •

edited

Loading

vsemozhetbyt commented Apr 20, 2018 •

edited

Loading

BridgeAR commented Apr 25, 2018 •

edited

Loading