lukechilds
/
node
mirror of https://github.com/lukechilds/node.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

doc: update backporting guide 

* also update STYLE_GUIDE comment about Em dashes

PR-URL: https://github.com/nodejs/node/pull/13749
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
v6.x
Refael Ackermann 8 years ago
committed by Myles Borins
parent
e2abda87f5
commit
092bba5cbf
No known key found for this signature in database GPG Key ID: 933B01F40B5CA946
2 changed files with 50 additions and 54 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 6
      doc/STYLE_GUIDE.md
  2. 98
      doc/guides/backporting-to-release-lines.md

6
doc/STYLE_GUIDE.md
View File

@ -40,8 +40,8 @@
* When documenting APIs, note the version the API was introduced in at * When documenting APIs, note the version the API was introduced in at
the end of the section. If an API has been deprecated, also note the first the end of the section. If an API has been deprecated, also note the first
version that the API appeared deprecated in. version that the API appeared deprecated in.
* When using dashes, use emdashes ("—", Option+Shift+"-" on macOS) surrounded by * When using dashes, use [Em dashes][] ("—" or `Option+Shift+"-"` on macOS)
spaces, per the New York Times usage. surrounded by spaces, as per [The New York Times Manual of Style and Usage][].
* Including assets: * Including assets:
* If you wish to add an illustration or full program, add it to the * If you wish to add an illustration or full program, add it to the
appropriate sub-directory in the `assets/` dir. appropriate sub-directory in the `assets/` dir.
@ -64,3 +64,5 @@
[plugin]: http://editorconfig.org/#download [plugin]: http://editorconfig.org/#download
[Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma [Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma
[Em dashes]: https://en.wikipedia.org/wiki/Dash#Em_dash
[The New York Times Manual of Style and Usage]: https://en.wikipedia.org/wiki/The_New_York_Times_Manual_of_Style_and_Usage

98
doc/guides/backporting-to-release-lines.md
View File

@ -6,58 +6,49 @@ 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: pad while preparing a release. The branch name is formatted as follows:
`vN.x-staging` where `N` is the major release number. `vN.x-staging` where `N` is the major release number.
### Active staging branches *Note*: For the active staging branches see the [LTS Schedule][].
| Release Line | Staging Branch |
| ------------ | -------------- |
| `v7.x` | `v7.x-staging` |
| `v6.x` | `v6.x-staging` |
| `v4.x` | `v4.x-staging` |
## What needs to be backported? ## What needs to be backported?
If a cherry-pick from master does not land cleanly on a staging branch, the 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 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. line (e.g. `backport-requested-vN.x`), specifying to our tooling that this
The releaser will then add a comment that a backport is needed. pull request should not be included. The releaser will then add a comment
requesting that a backport pull request be made.
## What can be backported? ## What can be backported?
The "Current" release line is much more lenient than the LTS release lines in 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) what can be landed. Our LTS release lines (see the [LTS Plan][])
require that commits mature in a Current release for at least 2 weeks before require that commits mature in the Current release for at least 2 weeks before
they can be landed on staging. If the commit can not be cherry-picked from they can be landed in an LTS staging branch. Only after "maturation" will those
master a manual backport will need to be submitted. Please see the [LTS Plan][] commits be cherry-picked or backported.
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 ## How to submit a backport pull request
For these steps, let's assume that a backport is needed for the v7.x release For the following steps, let's assume that a backport is needed for the v6.x
line. All commands will use the v7.x-staging branch as the target branch. release line. All commands will use the `v6.x-staging` branch as the target
In order to submit a backport pull request to another branch, simply replace branch. In order to submit a backport pull request to another branch, simply
that with the staging branch for the targeted release line. replace that with the staging branch for the targeted release line.
* Checkout the staging branch for the targeted release line 1. Checkout the staging branch for the targeted release line
* Make sure that the local staging branch is up to date with the remote 2. Make sure that the local staging branch is up to date with the remote
* Create a new branch off of the staging branch 3. Create a new branch off of the staging branch
```shell ```shell
# Assuming your fork of Node.js is checked out in $NODE_DIR, # Assuming your fork of Node.js is checked out in $NODE_DIR,
# the origin remote points to your fork, and the upstream remote points # the origin remote points to your fork, and the upstream remote points
# to git://github.com/nodejs/node # to git://github.com/nodejs/node
cd $NODE_DIR cd $NODE_DIR
# Fails if you already have a v7.x-staging # If v6.x-staging is checked out `pull` should be used instead of `fetch`
git branch v7.x-staging upstream/v7.x-staging git fetch upstream v6.x-staging:v6.x-staging -f
git checkout v7.x-staging # Assume we want to backport PR #10157
git reset --hard upstream/v7.x-staging git checkout -b backport-10157-to-v6.x v6.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 4. 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: will likely fail due to conflicts. In that case, you will see something
like this:
```shell ```shell
# Say the $SHA is 773cdc31ef # Say the $SHA is 773cdc31ef
@ -68,25 +59,28 @@ hint: with 'git add <paths>' or 'git rm <paths>'
hint: and commit the result with 'git commit' hint: and commit the result with 'git commit'
``` ```
* Make the required changes to remove the conflicts, add the files to the index 5. 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 using `git add`, and then commit the changes. That can be done with
`git cherry-pick --continue`. `git cherry-pick --continue`.
* Leave the commit message as is. If you think it should be modified, comment 6. Leave the commit message as is. If you think it should be modified, comment
in the Pull Request. in the Pull Request.
* Make sure `make -j4 test` passes 7. Make sure `make -j4 test` passes.
* Push the changes to your fork and open a pull request. 8. Push the changes to your fork
* Be sure to target the `v7.x-staging` branch in the pull request. 9. Open a pull request:
1. Be sure to target the `v6.x-staging` branch in the pull request.
### Helpful Hints 2. Include the backport target in the pull request title in the following
format — `[v6.x backport] <commit title>`.
* Please include the backport target in the pull request title in the following Example: `[v6.x backport] process: improve performance of nextTick`
format: `(v7.x backport) <commit title>` 3. Check the checkbox labelled "Allow edits from maintainers".
* Ex. `(v4.x backport) process: improve performance of nextTick` 4. In the description add a reference to the original PR
* Please check the checkbox labelled "Allow edits from maintainers". 5. Run a [`node-test-pull-request`][] CI job (with `REBASE_ONTO` set to the
This is the easiest way to to avoid constant rebases. default `<pr base branch>`)
10. If during the review process conflicts arise, use the following to rebase:
In the event the backport pull request is different than the original, `git pull --rebase upstream v6.x-staging`
the backport pull request should be reviewed the same way a new pull request
is reviewed. After the PR lands replace the `backport-requested-v6.x` label on the original
PR with `backported-to-v6.x`.
[LTS Schedule]: https://github.com/nodejs/LTS/#lts-schedule1
[LTS Plan]: https://github.com/nodejs/LTS#lts-plan [LTS Plan]: https://github.com/nodejs/LTS#lts-plan
[`node-test-pull-request`]: https://ci.nodejs.org/job/node-test-pull-request/build

Write Preview
Loading…
Cancel
Save