From a63d3c514d56fff548957e465b7b055bdaf298bb Mon Sep 17 00:00:00 2001 From: Ruben Bridgewater Date: Sun, 17 Dec 2017 12:59:46 -0300 Subject: [PATCH] doc: update formatting to fit our 80 chars rule This will also use a proper indentation as a couple of entries had a extra indentation of two spaces. PR-URL: https://github.com/nodejs/node/pull/17722 Reviewed-By: Jon Moss Reviewed-By: Luigi Pinca Reviewed-By: James M Snell Reviewed-By: Daniel Bevenius --- doc/guides/building-node-with-ninja.md | 25 +- doc/guides/maintaining-V8.md | 56 ++-- doc/guides/maintaining-npm.md | 4 +- doc/onboarding-extras.md | 50 +++- doc/onboarding.md | 323 +++++++++++--------- doc/releases.md | 389 ++++++++++++++++++------- 6 files changed, 552 insertions(+), 295 deletions(-) diff --git a/doc/guides/building-node-with-ninja.md b/doc/guides/building-node-with-ninja.md index 29b32c3d7277de..5473d662be2f27 100644 --- a/doc/guides/building-node-with-ninja.md +++ b/doc/guides/building-node-with-ninja.md @@ -1,6 +1,8 @@ # Building Node with Ninja -The purpose of this guide is to show how to build Node.js using [Ninja][], as doing so can be significantly quicker than using `make`. Please see [Ninja's site][Ninja] for installation instructions (unix only). +The purpose of this guide is to show how to build Node.js using [Ninja][], as +doing so can be significantly quicker than using `make`. Please see +[Ninja's site][Ninja] for installation instructions (unix only). To build Node with ninja, there are 3 steps that must be taken: @@ -8,21 +10,27 @@ To build Node with ninja, there are 3 steps that must be taken: 2. Run `ninja -C out/Release` to produce a compiled release binary. 3. Lastly, make symlink to `./node` using `ln -fs out/Release/node node`. -When running `ninja -C out/Release` you will see output similar to the following if the build has succeeded: +When running `ninja -C out/Release` you will see output similar to the following +if the build has succeeded: + ```txt ninja: Entering directory `out/Release` [4/4] LINK node, POSTBUILDS ``` -The bottom line will change while building, showing the progress as `[finished/total]` build steps. -This is useful output that `make` does not produce and is one of the benefits of using Ninja. -Also, Ninja will likely compile much faster than even `make -j4` (or `-j`). +The bottom line will change while building, showing the progress as +`[finished/total]` build steps. This is useful output that `make` does not +produce and is one of the benefits of using Ninja. Also, Ninja will likely +compile much faster than even `make -j4` (or +`-j`). ## Considerations -Ninja builds vary slightly from `make` builds. If you wish to run `make test` after, `make` will likely still need to rebuild some amount of Node. +Ninja builds vary slightly from `make` builds. If you wish to run `make test` +after, `make` will likely still need to rebuild some amount of Node. -As such, if you wish to run the tests, it can be helpful to invoke the test runner directly, like so: +As such, if you wish to run the tests, it can be helpful to invoke the test +runner directly, like so: `tools/test.py --mode=release message parallel sequential -J` ## Alias @@ -31,7 +39,8 @@ As such, if you wish to run the tests, it can be helpful to invoke the test runn ## Producing a debug build -The above alias can be modified slightly to produce a debug build, rather than a release build as shown below: +The above alias can be modified slightly to produce a debug build, rather than a +release build as shown below: `alias nnodedebug='./configure --ninja && ninja -C out/Debug && ln -fs out/Debug/node node_g'` diff --git a/doc/guides/maintaining-V8.md b/doc/guides/maintaining-V8.md index 3d673b67d837ea..887c9a8766035a 100644 --- a/doc/guides/maintaining-V8.md +++ b/doc/guides/maintaining-V8.md @@ -157,8 +157,8 @@ process. * Unfixed bugs. The bug exists in the V8 master branch. * Fixed, but needs backport. The bug may need porting to one or more branches. - * Backporting to active branches. - * Backporting to abandoned branches. + * Backporting to active branches. + * Backporting to abandoned branches. * Backports identified by the V8 team. Bugs identified by upstream V8 that we haven't encountered in Node.js yet. @@ -188,14 +188,14 @@ backport the fix: * Identify which version of V8 the bug was fixed in. * Identify if any active V8 branches still contain the bug: * A tracking bug is needed to request a backport. - * If there isn't already a V8 bug tracking the fix, open a new merge request - bug using this [Node.js specific template][V8TemplateMergeRequest]. - * If a bug already exists - * Add a reference to the GitHub issue. - * Attach *merge-request-x.x* labels to the bug for any active branches - that still contain the bug. (e.g. merge-request-5.3, - merge-request-5.4) - * Add ofrobots-at-google.com to the cc list. + * If there isn't already a V8 bug tracking the fix, open a new merge request + bug using this [Node.js specific template][V8TemplateMergeRequest]. + * If a bug already exists + * Add a reference to the GitHub issue. + * Attach *merge-request-x.x* labels to the bug for any active branches + that still contain the bug. (e.g. merge-request-5.3, + merge-request-5.4) + * Add ofrobots-at-google.com to the cc list. * Once the merge has been approved, it should be merged using the [merge script documented in the V8 wiki][V8MergingPatching]. Merging requires commit access to the V8 repository. If you don't have commit access you can @@ -214,24 +214,24 @@ to be cherry-picked in the Node.js repository and V8-CI must test the change. * For each abandoned V8 branch corresponding to an LTS branch that is affected by the bug: - * Checkout a branch off the appropriate *vY.x-staging* branch (e.g. - *v6.x-staging* to fix an issue in V8 5.1). - * Cherry-pick the commit(s) from the V8 repository. - * On Node.js < 9.0.0: Increase the patch level version in `v8-version.h`. - This will not cause any problems with versioning because V8 will not - publish other patches for this branch, so Node.js can effectively bump the - patch version. - * On Node.js >= 9.0.0: Increase the `v8_embedder_string` number in - `common.gypi`. - * In some cases the patch may require extra effort to merge in case V8 has - changed substantially. For important issues we may be able to lean on the - V8 team to get help with reimplementing the patch. - * Open a cherry-pick PR on `nodejs/node` targeting the *vY.x-staging* branch - and notify the `@nodejs/v8` team. - * Run the Node.js [V8 CI] in addition to the [Node.js CI]. - Note: The CI uses the `test-v8` target in the `Makefile`, which uses - `tools/make-v8.sh` to reconstruct a git tree in the `deps/v8` directory to - run V8 tests. + * Checkout a branch off the appropriate *vY.x-staging* branch (e.g. + *v6.x-staging* to fix an issue in V8 5.1). + * Cherry-pick the commit(s) from the V8 repository. + * On Node.js < 9.0.0: Increase the patch level version in `v8-version.h`. + This will not cause any problems with versioning because V8 will not + publish other patches for this branch, so Node.js can effectively bump the + patch version. + * On Node.js >= 9.0.0: Increase the `v8_embedder_string` number in + `common.gypi`. + * In some cases the patch may require extra effort to merge in case V8 has + changed substantially. For important issues we may be able to lean on the + V8 team to get help with reimplementing the patch. + * Open a cherry-pick PR on `nodejs/node` targeting the *vY.x-staging* branch + and notify the `@nodejs/v8` team. + * Run the Node.js [V8 CI] in addition to the [Node.js CI]. + Note: The CI uses the `test-v8` target in the `Makefile`, which uses + `tools/make-v8.sh` to reconstruct a git tree in the `deps/v8` directory to + run V8 tests. The [`update-v8`] tool can be used to simplify this task. Run `update-v8 backport --sha=SHA` to cherry-pick a commit. diff --git a/doc/guides/maintaining-npm.md b/doc/guides/maintaining-npm.md index af9d3af04f2360..97da87feee64d3 100644 --- a/doc/guides/maintaining-npm.md +++ b/doc/guides/maintaining-npm.md @@ -21,7 +21,9 @@ $ git checkout vX.Y.Z $ make release ``` -Note: please run `npm dist-tag ls npm` and make sure this is the `latest` **dist-tag**. `latest` on git is usually released as `next` when it's time to downstream +Note: please run `npm dist-tag ls npm` and make sure this is the `latest` +**dist-tag**. `latest` on git is usually released as `next` when it's time to +downstream ## Step 3: Remove old npm diff --git a/doc/onboarding-extras.md b/doc/onboarding-extras.md index 0da3b1b5259f3a..a010d8fef1fe41 100644 --- a/doc/onboarding-extras.md +++ b/doc/onboarding-extras.md @@ -42,7 +42,8 @@ | upgrading npm | @fishrock123, @MylesBorins | | upgrading V8 | @nodejs/v8, @nodejs/post-mortem | -When things need extra attention, are controversial, or `semver-major`: @nodejs/tsc +When things need extra attention, are controversial, or `semver-major`: +@nodejs/tsc If you cannot find who to cc for a file, `git shortlog -n -s ` may help. @@ -51,12 +52,14 @@ If you cannot find who to cc for a file, `git shortlog -n -s ` may help. ### By Subsystem -We generally sort issues by a concept of "subsystem" so that we know what part(s) of the codebase it touches. +We generally sort issues by a concept of "subsystem" so that we know what +part(s) of the codebase it touches. **Subsystems generally are**: * `lib/*.js` -* `doc`, `build`, `tools`, `test`, `deps`, `lib / src` (special), and there may be others. +* `doc`, `build`, `tools`, `test`, `deps`, `lib / src` (special), and there may + be others. * `meta` for anything non-code (process) related There may be more than one subsystem valid for any particular issue / PR. @@ -74,13 +77,19 @@ Please use these when possible / appropriate -- * `semver-{minor,major}` - * be conservative – that is, if a change has the remote *chance* of breaking something, go for semver-major + * be conservative – that is, if a change has the remote *chance* of breaking + something, go for semver-major * when adding a semver label, add a comment explaining why you're adding it - * minor vs. patch: roughly: "does it add a new method / does it add a new section to the docs" - * major vs. everything else: run last versions tests against this version, if they pass, **probably** minor or patch - * A breaking change helper ([full source](https://gist.github.com/chrisdickinson/ba532fa0e4e243fb7b44)): + * minor vs. patch: roughly: "does it add a new method / does it add a new + section to the docs" + * major vs. everything else: run last versions tests against this version, if + they pass, **probably** minor or patch + * A breaking change helper + ([full source](https://gist.github.com/chrisdickinson/ba532fa0e4e243fb7b44)): ```sh - git checkout $(git show -s --pretty='%T' $(git show-ref -d $(git describe --abbrev=0) | tail -n1 | awk '{print $1}')) -- test; make -j4 test + SHOW=$(git show-ref -d $(git describe --abbrev=0) | tail -n1 | awk '{print $1}') + git checkout $(git show -s --pretty='%T' $SHOW) -- test + make -j4 test ``` ### LTS/Version labels @@ -92,21 +101,28 @@ We use labels to keep track of which branches a commit should land on: * Also used when the work of backporting a change outweighs the benefits * `land-on-v?.x` * Used by releasers to mark a PR as scheduled for inclusion in an LTS release - * Applied to the original PR for clean cherry-picks, to the backport PR otherwise + * Applied to the original PR for clean cherry-picks, to the backport PR + otherwise * `backport-requested-v?.x` - * Used to indicate that a PR needs a manual backport to a branch in order to land the changes on that branch - * Typically applied by a releaser when the PR does not apply cleanly or it breaks the tests after applying + * Used to indicate that a PR needs a manual backport to a branch in order to + land the changes on that branch + * Typically applied by a releaser when the PR does not apply cleanly or it + breaks the tests after applying * Will be replaced by either `dont-land-on-v?.x` or `backported-to-v?.x` * `backported-to-v?.x` * Applied to PRs for which a backport PR has been merged * `lts-watch-v?.x` - * Applied to PRs which the LTS working group should consider including in a LTS release - * Does not indicate that any specific action will be taken, but can be effective as messaging to non-collaborators + * Applied to PRs which the LTS working group should consider including in a + LTS release + * Does not indicate that any specific action will be taken, but can be + effective as messaging to non-collaborators * `lts-agenda` * For things that need discussion by the LTS working group - * (for example semver-minor changes that need or should go into an LTS release) + * (for example semver-minor changes that need or should go into an LTS + release) * `v?.x` - * Automatically applied to changes that do not target `master` but rather the `v?.x-staging` branch + * Automatically applied to changes that do not target `master` but rather the + `v?.x-staging` branch Once a release line enters maintenance mode, the corresponding labels do not need to be attached anymore, as only important bugfixes will be included. @@ -126,6 +142,7 @@ need to be attached anymore, as only important bugfixes will be included. * `git remote add upstream git://github.com/nodejs/node.git` to update from nodejs/node: + * `git checkout master` * `git remote update -p` OR `git fetch --all` (I prefer the former) * `git merge --ff-only upstream/master` (or `REMOTENAME/BRANCH`) @@ -135,5 +152,6 @@ to update from nodejs/node: * commit often, out to your github fork (origin), open a PR * when making PRs make sure to spend time on the description: - * every moment you spend writing a good description quarters the amount of time it takes to understand your code. + * every moment you spend writing a good description quarters the amount of + time it takes to understand your code. * usually prefer to only squash at the *end* of your work, depends on the change diff --git a/doc/onboarding.md b/doc/onboarding.md index af6407c4164455..37e250d558c10e 100644 --- a/doc/onboarding.md +++ b/doc/onboarding.md @@ -15,173 +15,216 @@ onboarding session. * Prior to the onboarding session, add the new Collaborator to [the Collaborators team](https://github.com/orgs/nodejs/teams/collaborators), and to [the Members team](https://github.com/orgs/nodejs/teams/members) if - they are not already part of it. - Note that this is the step that gives the account elevated privileges, so - do not perform this step (or any subsequent steps) unless two-factor - authentication is enabled on the new Collaborator's GitHub account. - + they are not already part of it. Note that this is the step that gives the + account elevated privileges, so do not perform this step (or any subsequent + steps) unless two-factor authentication is enabled on the new Collaborator's + GitHub account. ## Onboarding session * This session will cover: - * [local setup](#local-setup) - * [project goals & values](#project-goals--values) - * [managing the issue tracker](#managing-the-issue-tracker) - * [reviewing PRs](#reviewing-prs) - * [landing PRs](#landing-prs) + * [local setup](#local-setup) + * [project goals & values](#project-goals--values) + * [managing the issue tracker](#managing-the-issue-tracker) + * [reviewing PRs](#reviewing-prs) + * [landing PRs](#landing-prs) ## Local setup - * git: - * Make sure you have whitespace=fix: `git config --global --add apply.whitespace fix` - * Always continue to PR from your own github fork - * Branches in the nodejs/node repository are only for release lines - * [See "Updating Node.js from Upstream"](./onboarding-extras.md#updating-nodejs-from-upstream) - * Make a new branch for each PR you submit. - * Membership: Consider making your membership in the Node.js GitHub organization - public. This makes it easier to identify Collaborators. Instructions on how to - do that are available at - [Publicizing or hiding organization membership](https://help.github.com/articles/publicizing-or-hiding-organization-membership/). - - * Notifications: - * Use [https://github.com/notifications](https://github.com/notifications) or set up email - * Watching the main repo will flood your inbox (several hundred notifications on typical weekdays), so be prepared - - * `#node-dev` on [webchat.freenode.net](https://webchat.freenode.net/) is the best place to interact with the TSC / other Collaborators - * If there are any questions after the session, a good place to ask is there! - * Presence is not mandatory, but please drop a note there if force-pushing to `master` - +* git: + * Make sure you have whitespace=fix: `git config --global --add + apply.whitespace fix` + * Always continue to PR from your own github fork + * Branches in the nodejs/node repository are only for release lines + * [See "Updating Node.js from Upstream"][] + * Make a new branch for each PR you submit. + * Membership: Consider making your membership in the Node.js GitHub + organization public. This makes it easier to identify Collaborators. + Instructions on how to do that are available at + [Publicizing or hiding organization membership][]. + +* Notifications: + * Use [https://github.com/notifications](https://github.com/notifications) or + set up email + * Watching the main repo will flood your inbox (several hundred notifications + on typical weekdays), so be prepared + +* `#node-dev` on [webchat.freenode.net](https://webchat.freenode.net/) is the + best place to interact with the TSC / other Collaborators + * If there are any questions after the session, a good place to ask is there! + * Presence is not mandatory, but please drop a note there if force-pushing to + `master` ## Project goals & values - * Collaborators are the collective owners of the project - * The project has the goals of its contributors +* Collaborators are the collective owners of the project + * The project has the goals of its contributors - * There are some higher-level goals and values - * Empathy towards users matters (this is in part why we onboard people) - * Generally: try to be nice to people! - * The best outcome is for people who come to our issue tracker to feel like they can come back again. +* There are some higher-level goals and values + * Empathy towards users matters (this is in part why we onboard people) + * Generally: try to be nice to people! + * The best outcome is for people who come to our issue tracker to feel like + they can come back again. - * We have a [Code of Conduct][] that you are expected to follow *and* hold others accountable to +* We have a [Code of Conduct][] that you are expected to follow *and* hold + others accountable to ## Managing the issue tracker - * You have (mostly) free rein; don't hesitate to close an issue if you are confident that it should be closed - * Be nice about closing issues! Let people know why, and that issues and PRs can be reopened if necessary - - * [**See "Labels"**](./onboarding-extras.md#labels) - * There is [a bot](https://github.com/nodejs-github-bot/github-bot) that applies subsystem labels (for example, `doc`, `test`, `assert`, or `buffer`) so that we know what parts of the code base the pull request modifies. It is not perfect, of course. Feel free to apply relevant labels and remove irrelevant labels from pull requests and issues. - * Use the `tsc-review` label if a topic is controversial or isn't coming to - a conclusion after an extended time. - * `semver-{minor,major}`: - * If a change has the remote *chance* of breaking something, use the `semver-major` label - * When adding a semver label, add a comment explaining why you're adding it. Do it right away so you don't forget! - - * [**See "Who to CC in issues"**](./onboarding-extras.md#who-to-cc-in-issues) - * This will come more naturally over time - * For many of the teams listed there, you can ask to be added if you are interested - * Some are WGs with some process around adding people, others are only there for notifications - - * When a discussion gets heated, you can request that other Collaborators keep an eye on it by opening an issue at the private [nodejs/moderation](https://github.com/nodejs/moderation) repository. - * This is a repository to which all members of the `nodejs` GitHub organization (not just Collaborators on Node.js core) have access. Its contents should not be shared externally. - * You can find the full moderation policy [here](https://github.com/nodejs/TSC/blob/master/Moderation-Policy.md). +* You have (mostly) free rein; don't hesitate to close an issue if you are + confident that it should be closed + * Be nice about closing issues! Let people know why, and that issues and PRs + can be reopened if necessary + +* [**See "Labels"**](./onboarding-extras.md#labels) + * There is [a bot](https://github.com/nodejs-github-bot/github-bot) that + applies subsystem labels (for example, `doc`, `test`, `assert`, or `buffer`) + so that we know what parts of the code base the pull request modifies. It is + not perfect, of course. Feel free to apply relevant labels and remove + irrelevant labels from pull requests and issues. + * Use the `tsc-review` label if a topic is controversial or isn't coming to a + conclusion after an extended time. + * `semver-{minor,major}`: + * If a change has the remote *chance* of breaking something, use the + `semver-major` label + * When adding a semver label, add a comment explaining why you're adding it. + Do it right away so you don't forget! + +* [**See "Who to CC in issues"**](./onboarding-extras.md#who-to-cc-in-issues) + * This will come more naturally over time + * For many of the teams listed there, you can ask to be added if you are + interested + * Some are WGs with some process around adding people, others are only there + for notifications + +* When a discussion gets heated, you can request that other Collaborators keep + an eye on it by opening an issue at the private + [nodejs/moderation](https://github.com/nodejs/moderation) repository. + * This is a repository to which all members of the `nodejs` GitHub + organization (not just Collaborators on Node.js core) have access. Its + contents should not be shared externally. + * You can find the full moderation policy + [here](https://github.com/nodejs/TSC/blob/master/Moderation-Policy.md). ## Reviewing PRs - * The primary goal is for the codebase to improve. - * Secondary (but not far off) is for the person submitting code to succeed. - A pull request from a new contributor is an opportunity to grow the - community. - * Review a bit at a time. Do not overwhelm new contributors. - * It is tempting to micro-optimize and make everything about relative - performance. Don't succumb to that temptation. We change V8 often. - Techniques that provide improved performance today may be unnecessary in - the future. - * Be aware: Your opinion carries a lot of weight! - * Nits (requests for small changes that are not essential) are fine, but try - to avoid stalling the pull request. - * Note that they are nits when you comment: `Nit: change foo() to bar().` - * If they are stalling the pull request, fix them yourself on merge. - * Minimum wait for comments time - * There is a minimum waiting time which we try to respect for non-trivial - changes, so that people who may have important input in such a - distributed project are able to respond. - * For non-trivial changes, leave the pull request open for at least 48 - hours (72 hours on a weekend). - * If a pull request is abandoned, check if they'd mind if you took it over - (especially if it just has nits left). - * Approving a change - * Collaborators indicate that they have reviewed and approve of the - changes in a pull request using Github’s approval interface - * Some people like to comment `LGTM` (“Looks Good To Me”) - * You have the authority to approve any other collaborator’s work. - * You cannot approve your own pull requests. - * When explicitly using `Changes requested`, show empathy – comments will - usually be addressed even if you don’t use it. - * If you do, it is nice if you are available later to check whether your - comments have been addressed - * If you see that the requested changes have been made, you can clear another collaborator's - `Changes requested` review. - * Use `Changes requested` to indicate that you are considering some of - your comments to block the PR from landing. - - * What belongs in Node.js: - * Opinions vary – it’s good to have a broad collaborator base for that reason! - * If Node.js itself needs it (due to historic reasons), then it belongs in Node.js - * That is to say, url is there because of http, freelist is there because of http, etc. - * Things that cannot be done outside of core, or only with significant pain (for example `async_hooks`) - - * Continuous Integration (CI) Testing: - * [https://ci.nodejs.org/](https://ci.nodejs.org/) - * It is not automatically run. You need to start it manually. - * Log in on CI is integrated with GitHub. Try to log in now! - * You will be using `node-test-pull-request` most of the time. Go there now! - * Consider bookmarking it: https://ci.nodejs.org/job/node-test-pull-request/ - * To get to the form to start a job, click on `Build with Parameters`. (If you don't see it, that probably means you are not logged in!) Click it now! - * To start CI testing from this screen, you need to fill in two elements on the form: - * The `CERTIFY_SAFE` box should be checked. By checking it, you are indicating that you have reviewed the code you are about to test and you are confident that it does not contain any malicious code. (We don't want people hijacking our CI hosts to attack other hosts on the internet, for example!) - * The `PR_ID` box should be filled in with the number identifying the pull request containing the code you wish to test. For example, if the URL for the pull request is `https://github.com/nodejs/node/issues/7006`, then put `7006` in the `PR_ID`. - * The remaining elements on the form are typically unchanged with the exception of `POST_STATUS_TO_PR`. Check that if you want a CI status indicator to be automatically inserted into the PR. - * If you need help with something CI-related: - * Use #node-dev (IRC) to talk to other Collaborators. - * Use #node-build (IRC) to talk to the Build WG members who maintain the CI infrastructure. - * Use the [Build WG repo](https://github.com/nodejs/build) to file issues for the Build WG members who maintain the CI infrastructure. - +* The primary goal is for the codebase to improve. +* Secondary (but not far off) is for the person submitting code to succeed. A + pull request from a new contributor is an opportunity to grow the community. +* Review a bit at a time. Do not overwhelm new contributors. + * It is tempting to micro-optimize and make everything about relative + performance. Don't succumb to that temptation. We change V8 often. + Techniques that provide improved performance today may be unnecessary in + the future. +* Be aware: Your opinion carries a lot of weight! +* Nits (requests for small changes that are not essential) are fine, but try to + avoid stalling the pull request. + * Note that they are nits when you comment: `Nit: change foo() to bar().` + * If they are stalling the pull request, fix them yourself on merge. +* Minimum wait for comments time + * There is a minimum waiting time which we try to respect for non-trivial + changes, so that people who may have important input in such a distributed + project are able to respond. + * For non-trivial changes, leave the pull request open for at least 48 hours + (72 hours on a weekend). + * If a pull request is abandoned, check if they'd mind if you took it over + (especially if it just has nits left). +* Approving a change + * Collaborators indicate that they have reviewed and approve of the changes in + a pull request using Github’s approval interface + * Some people like to comment `LGTM` (“Looks Good To Me”) + * You have the authority to approve any other collaborator’s work. + * You cannot approve your own pull requests. + * When explicitly using `Changes requested`, show empathy – comments will + usually be addressed even if you don’t use it. + * If you do, it is nice if you are available later to check whether your + comments have been addressed + * If you see that the requested changes have been made, you can clear + another collaborator's `Changes requested` review. + * Use `Changes requested` to indicate that you are considering some of your + comments to block the PR from landing. + +* What belongs in Node.js: + * Opinions vary – it’s good to have a broad collaborator base for that reason! + * If Node.js itself needs it (due to historic reasons), then it belongs in + Node.js + * That is to say, url is there because of http, freelist is there because of + http, etc. + * Things that cannot be done outside of core, or only with significant pain + (for example `async_hooks`) + +* Continuous Integration (CI) Testing: + * [https://ci.nodejs.org/](https://ci.nodejs.org/) + * It is not automatically run. You need to start it manually. + * Log in on CI is integrated with GitHub. Try to log in now! + * You will be using `node-test-pull-request` most of the time. Go there now! + * Consider bookmarking it: https://ci.nodejs.org/job/node-test-pull-request/ + * To get to the form to start a job, click on `Build with Parameters`. (If you + don't see it, that probably means you are not logged in!) Click it now! + * To start CI testing from this screen, you need to fill in two elements on + the form: + * The `CERTIFY_SAFE` box should be checked. By checking it, you are + indicating that you have reviewed the code you are about to test and you + are confident that it does not contain any malicious code. (We don't want + people hijacking our CI hosts to attack other hosts on the internet, for + example!) + * The `PR_ID` box should be filled in with the number identifying the pull + request containing the code you wish to test. For example, if the URL for + the pull request is `https://github.com/nodejs/node/issues/7006`, then put + `7006` in the `PR_ID`. + * The remaining elements on the form are typically unchanged with the + exception of `POST_STATUS_TO_PR`. Check that if you want a CI status + indicator to be automatically inserted into the PR. + * If you need help with something CI-related: + * Use #node-dev (IRC) to talk to other Collaborators. + * Use #node-build (IRC) to talk to the Build WG members who maintain the CI + infrastructure. + * Use the [Build WG repo](https://github.com/nodejs/build) to file issues + for the Build WG members who maintain the CI infrastructure. ## Landing PRs - * [See the Collaborator Guide: Landing Pull Requests](https://github.com/nodejs/node/blob/master/COLLABORATOR_GUIDE.md#landing-pull-requests) +* See the Collaborator Guide: [Landing Pull Requests][] ## Exercise: Make a PR adding yourself to the README - * Example: [https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0](https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0) - * For raw commit message: `git log ce986de829457c39257cd205067602e765768fb0 -1` - * Collaborators are in alphabetical order by GitHub username. - * Optionally, include your personal pronouns. - * Label your pull request with the `doc` subsystem label. - * Run CI on your PR. - * After one or two approvals, land the PR. - * Be sure to add the `PR-URL: ` and appropriate `Reviewed-By:` metadata! - * [`core-validate-commit`][] helps a lot with this – install and use it if you can! - * [`node-core-utils`][] fetches the metadata for you. +* Example: + [https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0][] + * For raw commit message: `git log ce986de829457c39257cd205067602e765768fb0 + -1` +* Collaborators are in alphabetical order by GitHub username. +* Optionally, include your personal pronouns. +* Label your pull request with the `doc` subsystem label. +* Run CI on your PR. +* After one or two approvals, land the PR. + * Be sure to add the `PR-URL: ` and appropriate `Reviewed-By:` + metadata! + * [`core-validate-commit`][] helps a lot with this – install and use it if you + can! + * [`node-core-utils`][] fetches the metadata for you. ## Final notes - * Don't worry about making mistakes: everybody makes them, there's a lot to internalize and that takes time (and we recognize that!) - * Almost any mistake you could make can be fixed or reverted. - * The existing Collaborators trust you and are grateful for your help! - * Other repositories: - * [https://github.com/nodejs/TSC](https://github.com/nodejs/TSC) - * [https://github.com/nodejs/build](https://github.com/nodejs/build) - * [https://github.com/nodejs/nodejs.org](https://github.com/nodejs/nodejs.org) - * [https://github.com/nodejs/readable-stream](https://github.com/nodejs/readable-stream) - * [https://github.com/nodejs/LTS](https://github.com/nodejs/LTS) - * [https://github.com/nodejs/citgm](https://github.com/nodejs/citgm) - * The Node.js Foundation hosts regular summits for active contributors to the Node.js - project, where we have face-to-face discussion about our work on the project. - The foundation has travel funds to cover participants' expenses including - accommodation, transportation, visa fees etc. if needed. Check out the - [summit](https://github.com/nodejs/summit) repository for details. +* Don't worry about making mistakes: everybody makes them, there's a lot to + internalize and that takes time (and we recognize that!) +* Almost any mistake you could make can be fixed or reverted. +* The existing Collaborators trust you and are grateful for your help! +* Other repositories: + * [https://github.com/nodejs/TSC](https://github.com/nodejs/TSC) + * [https://github.com/nodejs/build](https://github.com/nodejs/build) + * [https://github.com/nodejs/nodejs.org](https://github.com/nodejs/nodejs.org) + * [https://github.com/nodejs/readable-stream](https://github.com/nodejs/readable-stream) + * [https://github.com/nodejs/LTS](https://github.com/nodejs/LTS) + * [https://github.com/nodejs/citgm](https://github.com/nodejs/citgm) +* The Node.js Foundation hosts regular summits for active contributors to the + Node.js project, where we have face-to-face discussion about our work on the + project. The foundation has travel funds to cover participants' expenses + including accommodation, transportation, visa fees etc. if needed. Check out + the [summit](https://github.com/nodejs/summit) repository for details. [Code of Conduct]: https://github.com/nodejs/admin/blob/master/CODE_OF_CONDUCT.md [`core-validate-commit`]: https://github.com/evanlucas/core-validate-commit [`node-core-utils`]: https://github.com/nodejs/node-core-utils +[Landing Pull Requests]: https://github.com/nodejs/node/blob/master/COLLABORATOR_GUIDE.md#landing-pull-requests +[https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0]: https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0 +[Publicizing or hiding organization membership]: https://help.github.com/articles/publicizing-or-hiding-organization-membership/ +[See "Updating Node.js from Upstream"]: ./onboarding-extras.md#updating-nodejs-from-upstream diff --git a/doc/releases.md b/doc/releases.md index 36bdef8325acf6..dac16c3515966a 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -1,38 +1,67 @@ # Node.js Release Process -This document describes the technical aspects of the Node.js release process. The intended audience is those who have been authorized by the Node.js Foundation Technical Steering Committee (TSC) to create, promote, and sign official release builds for Node.js, hosted on . +This document describes the technical aspects of the Node.js release process. +The intended audience is those who have been authorized by the Node.js +Foundation Technical Steering Committee (TSC) to create, promote, and sign +official release builds for Node.js, hosted on . ## Who can make a release? -Release authorization is given by the Node.js TSC. Once authorized, an individual must be have the following: +Release authorization is given by the Node.js TSC. Once authorized, an +individual must be have the following: ### 1. Jenkins Release Access There are three relevant Jenkins jobs that should be used for a release flow: -**a.** **Test runs:** **[node-test-pull-request](https://ci.nodejs.org/job/node-test-pull-request/)** is used for a final full-test run to ensure that the current *HEAD* is stable. +**a.** **Test runs:** +**[node-test-pull-request](https://ci.nodejs.org/job/node-test-pull-request/)** +is used for a final full-test run to ensure that the current *HEAD* is stable. -**b.** **Nightly builds:** (optional) **[iojs+release](https://ci-release.nodejs.org/job/iojs+release/)** can be used to create a nightly release for the current *HEAD* if public test releases are required. Builds triggered with this job are published straight to and are available for public download. +**b.** **Nightly builds:** (optional) +**[iojs+release](https://ci-release.nodejs.org/job/iojs+release/)** can be used +to create a nightly release for the current *HEAD* if public test releases are +required. Builds triggered with this job are published straight to + and are available for public download. -**c.** **Release builds:** **[iojs+release](https://ci-release.nodejs.org/job/iojs+release/)** does all of the work to build all required release assets. Promotion of the release files is a manual step once they are ready (see below). +**c.** **Release builds:** +**[iojs+release](https://ci-release.nodejs.org/job/iojs+release/)** does all of +the work to build all required release assets. Promotion of the release files is +a manual step once they are ready (see below). -The [Node.js build team](https://github.com/nodejs/build) is able to provide this access to individuals authorized by the TSC. +The [Node.js build team](https://github.com/nodejs/build) is able to provide +this access to individuals authorized by the TSC. ### 2. Access -The _dist_ user on nodejs.org controls the assets available in . is an alias for . +The _dist_ user on nodejs.org controls the assets available in +. is an alias for +. -The Jenkins release build workers upload their artifacts to the web server as the _staging_ user. The _dist_ user has access to move these assets to public access while, for security, the _staging_ user does not. +The Jenkins release build workers upload their artifacts to the web server as +the _staging_ user. The _dist_ user has access to move these assets to public +access while, for security, the _staging_ user does not. -Nightly builds are promoted automatically on the server by a cron task for the _dist_ user. +Nightly builds are promoted automatically on the server by a cron task for the +_dist_ user. -Release builds require manual promotion by an individual with SSH access to the server as the _dist_ user. The [Node.js build team](https://github.com/nodejs/build) is able to provide this access to individuals authorized by the TSC. +Release builds require manual promotion by an individual with SSH access to the +server as the _dist_ user. The +[Node.js build team](https://github.com/nodejs/build) is able to provide this +access to individuals authorized by the TSC. ### 3. A Publicly Listed GPG Key -A SHASUMS256.txt file is produced for every promoted build, nightly, and releases. Additionally for releases, this file is signed by the individual responsible for that release. In order to be able to verify downloaded binaries, the public should be able to check that the SHASUMS256.txt file has been signed by someone who has been authorized to create a release. +A SHASUMS256.txt file is produced for every promoted build, nightly, and +releases. Additionally for releases, this file is signed by the individual +responsible for that release. In order to be able to verify downloaded binaries, +the public should be able to check that the SHASUMS256.txt file has been signed +by someone who has been authorized to create a release. -The GPG keys should be fetchable from a known third-party keyserver. The SKS Keyservers at are recommended. Use the [submission](https://pgp.mit.edu/) form to submit a new GPG key. Keys should be fetchable via: +The GPG keys should be fetchable from a known third-party keyserver. The SKS +Keyservers at are recommended. Use the +[submission](https://pgp.mit.edu/) form to submit a new GPG key. Keys should be +fetchable via: ```console $ gpg --keyserver pool.sks-keyservers.net --recv-keys @@ -40,18 +69,28 @@ $ gpg --keyserver pool.sks-keyservers.net --recv-keys The key you use may be a child/subkey of an existing key. -Additionally, full GPG key fingerprints for individuals authorized to release should be listed in the Node.js GitHub README.md file. +Additionally, full GPG key fingerprints for individuals authorized to release +should be listed in the Node.js GitHub README.md file. ## How to create a release Notes: - - Dates listed below as _"YYYY-MM-DD"_ should be the date of the release **as UTC**. Use `date -u +'%Y-%m-%d'` to find out what this is. - - Version strings are listed below as _"vx.y.z"_. Substitute for the release version. +- Dates listed below as _"YYYY-MM-DD"_ should be the date of the release **as + UTC**. Use `date -u +'%Y-%m-%d'` to find out what this is. +- Version strings are listed below as _"vx.y.z"_. Substitute for the release + version. ### 1. Cherry-picking from `master` and other branches -Create a new branch named _"vx.y.z-proposal"_, or something similar. Using `git cherry-pick`, bring the appropriate commits into your new branch. To determine the relevant commits, use [`branch-diff`](https://github.com/rvagg/branch-diff) and [`changelog-maker`](https://github.com/rvagg/changelog-maker/) (both are available on npm and should be installed globally). These tools depend on our commit metadata, as well as the `semver-minor` and `semver-major` GitHub labels. One drawback is that when the `PR-URL` metadata is accidentally omitted from a commit, the commit will show up because it's unsure if it's a duplicate or not. +Create a new branch named _"vx.y.z-proposal"_, or something similar. Using `git +cherry-pick`, bring the appropriate commits into your new branch. To determine +the relevant commits, use [`branch-diff`](https://github.com/rvagg/branch-diff) +and [`changelog-maker`](https://github.com/rvagg/changelog-maker/) (both are +available on npm and should be installed globally). These tools depend on our +commit metadata, as well as the `semver-minor` and `semver-major` GitHub labels. +One drawback is that when the `PR-URL` metadata is accidentally omitted from a +commit, the commit will show up because it's unsure if it's a duplicate or not. For a list of commits that could be landed in a patch release on v5.x @@ -59,11 +98,15 @@ For a list of commits that could be landed in a patch release on v5.x $ branch-diff v5.x master --exclude-label=semver-major,semver-minor,dont-land-on-v5.x --filter-release --format=simple ``` -Carefully review the list of commits looking for errors (incorrect `PR-URL`, incorrect semver, etc.). Commits labeled as semver minor or semver major should only be cherry-picked when appropriate for the type of release being made. Previous release commits and version bumps do not need to be cherry-picked. +Carefully review the list of commits looking for errors (incorrect `PR-URL`, +incorrect semver, etc.). Commits labeled as semver minor or semver major should +only be cherry-picked when appropriate for the type of release being made. +Previous release commits and version bumps do not need to be cherry-picked. ### 2. Update `src/node_version.h` -Set the version for the proposed release using the following macros, which are already defined in `src/node_version.h`: +Set the version for the proposed release using the following macros, which are +already defined in `src/node_version.h`: ```c #define NODE_MAJOR_VERSION x @@ -71,7 +114,8 @@ Set the version for the proposed release using the following macros, which are a #define NODE_PATCH_VERSION z ``` -Set the `NODE_VERSION_IS_RELEASE` macro value to `1`. This causes the build to be produced with a version string that does not have a trailing pre-release tag: +Set the `NODE_VERSION_IS_RELEASE` macro value to `1`. This causes the build to +be produced with a version string that does not have a trailing pre-release tag: ```c #define NODE_VERSION_IS_RELEASE 1 @@ -79,26 +123,40 @@ Set the `NODE_VERSION_IS_RELEASE` macro value to `1`. This causes the build to b **Also consider whether to bump `NODE_MODULE_VERSION`**: -This macro is used to signal an ABI version for native addons. It currently has two common uses in the community: +This macro is used to signal an ABI version for native addons. It currently has +two common uses in the community: -* Determining what API to work against for compiling native addons, e.g. [NAN](https://github.com/nodejs/nan) uses it to form a compatibility-layer for much of what it wraps. -* Determining the ABI for downloading pre-built binaries of native addons, e.g. [node-pre-gyp](https://github.com/mapbox/node-pre-gyp) uses this value as exposed via `process.versions.modules` to help determine the appropriate binary to download at install-time. +- Determining what API to work against for compiling native addons, e.g. + [NAN](https://github.com/nodejs/nan) uses it to form a compatibility-layer for + much of what it wraps. +- Determining the ABI for downloading pre-built binaries of native addons, e.g. + [node-pre-gyp](https://github.com/mapbox/node-pre-gyp) uses this value as + exposed via `process.versions.modules` to help determine the appropriate + binary to download at install-time. -The general rule is to bump this version when there are _breaking ABI_ changes and also if there are non-trivial API changes. The rules are not yet strictly defined, so if in doubt, please confer with someone that will have a more informed perspective, such as a member of the NAN team. +The general rule is to bump this version when there are _breaking ABI_ changes +and also if there are non-trivial API changes. The rules are not yet strictly +defined, so if in doubt, please confer with someone that will have a more +informed perspective, such as a member of the NAN team. -*Note*: It is current TSC policy to bump major version when ABI changes. If you see a need to bump `NODE_MODULE_VERSION` then you should consult the TSC. Commits may need to be reverted or a major version bump may need to happen. +*Note*: It is current TSC policy to bump major version when ABI changes. If you +see a need to bump `NODE_MODULE_VERSION` then you should consult the TSC. +Commits may need to be reverted or a major version bump may need to happen. ### 3. Update the Changelog #### Step 1: Collecting the formatted list of changes: -Collect a formatted list of commits since the last release. Use [`changelog-maker`](https://github.com/rvagg/changelog-maker) to do this. +Collect a formatted list of commits since the last release. Use +[`changelog-maker`](https://github.com/rvagg/changelog-maker) to do this. ```console $ changelog-maker --group ``` -Note that changelog-maker counts commits since the last tag and if the last tag in the repository was not on the current branch you may have to supply a `--start-ref` argument: +Note that changelog-maker counts commits since the last tag and if the last tag +in the repository was not on the current branch you may have to supply a +`--start-ref` argument: ```console $ changelog-maker --group --start-ref v2.3.1 @@ -107,9 +165,9 @@ $ changelog-maker --group --start-ref v2.3.1 #### Step 2: Update the appropriate doc/changelogs/CHANGELOG_*.md file There is a separate `CHANGELOG_*.md` file for each major Node.js release line. -These are located in the `doc/changelogs/` directory. Once the formatted list -of changes is collected, it must be added to the top of the relevant changelog -file in the release branch (e.g. a release for Node.js v4 would be added to the +These are located in the `doc/changelogs/` directory. Once the formatted list of +changes is collected, it must be added to the top of the relevant changelog file +in the release branch (e.g. a release for Node.js v4 would be added to the `/doc/changelogs/CHANGELOG_V4.md`). **Please do *not* add the changelog entries to the root `CHANGELOG.md` file.** @@ -132,19 +190,20 @@ The new entry should take the following form: * Include the full list of commits since the last release here. Do not include "Working on X.Y.Z+1" commits. ``` -The release type should be either Current, LTS, or Maintenance, depending on the type of release being produced. +The release type should be either Current, LTS, or Maintenance, depending on the +type of release being produced. -Be sure that the `` tag, as well as the two headings, are not -indented at all. +Be sure that the `` tag, as well as the two headings, are not indented at +all. At the top of each `CHANGELOG_*.md` file, and in the root `CHANGELOG.md` file, -there is a table indexing all releases in each major release line. A link to -the new release needs to be added to each. Follow the existing examples and be -sure to add the release to the *top* of the list. +there is a table indexing all releases in each major release line. A link to the +new release needs to be added to each. Follow the existing examples and be sure +to add the release to the *top* of the list. In the root `CHANGELOG.md` file, the most recent release for each release line -is shown in **bold** in the index. When updating the index, please make sure -to update the display accordingly by removing the bold styling from the previous +is shown in **bold** in the index. When updating the index, please make sure to +update the display accordingly by removing the bold styling from the previous release. #### Step 3: Update any REPLACEME and DEP00XX tags in the docs @@ -152,10 +211,10 @@ release. If this release includes new APIs then it is necessary to document that they were first added in this version. The relevant commits should already include `REPLACEME` tags as per the example in the -[docs README](../tools/doc/README.md). Check for these tags with -`grep REPLACEME doc/api/*.md`, and substitute this node version with -`sed -i "s/REPLACEME/$VERSION/g" doc/api/*.md` or -`perl -pi -e "s/REPLACEME/$VERSION/g" doc/api/*.md`. +[docs README](../tools/doc/README.md). Check for these tags with `grep REPLACEME +doc/api/*.md`, and substitute this node version with `sed -i +"s/REPLACEME/$VERSION/g" doc/api/*.md` or `perl -pi -e "s/REPLACEME/$VERSION/g" +doc/api/*.md`. *Note*: `$VERSION` should be prefixed with a `v` @@ -163,8 +222,8 @@ If this release includes any new deprecations it is necessary to ensure that those are assigned a proper static deprecation code. These are listed in the docs (see `doc/api/deprecations.md`) and in the source as `DEP00XX`. The code must be assigned a number (e.g. `DEP0012`). Note that this assignment should -occur when the PR is landed, but a check will be made when the release built -is run. +occur when the PR is landed, but a check will be made when the release built is +run. ### 4. Create Release Commit @@ -182,51 +241,112 @@ Notable changes: ### 5. Propose Release on GitHub -Push the release branch to `nodejs/node`, not to your own fork. This allows release branches to more easily be passed between members of the release team if necessary. +Push the release branch to `nodejs/node`, not to your own fork. This allows +release branches to more easily be passed between members of the release team if +necessary. -Create a pull request targeting the correct release line. For example, a v5.3.0-proposal PR should target v5.x, not master. Paste the CHANGELOG modifications into the body of the PR so that collaborators can see what is changing. These PRs should be left open for at least 24 hours, and can be updated as new commits land. +Create a pull request targeting the correct release line. For example, a +v5.3.0-proposal PR should target v5.x, not master. Paste the CHANGELOG +modifications into the body of the PR so that collaborators can see what is +changing. These PRs should be left open for at least 24 hours, and can be +updated as new commits land. -If you need any additional information about any of the commits, this PR is a good place to @-mention the relevant contributors. +If you need any additional information about any of the commits, this PR is a +good place to @-mention the relevant contributors. -This is also a good time to update the release commit to include `PR-URL` metadata. +This is also a good time to update the release commit to include `PR-URL` +metadata. ### 6. Ensure that the Release Branch is Stable -Run a **[node-test-pull-request](https://ci.nodejs.org/job/node-test-pull-request/)** test run to ensure that the build is stable and the HEAD commit is ready for release. +Run a +**[node-test-pull-request](https://ci.nodejs.org/job/node-test-pull-request/)** +test run to ensure that the build is stable and the HEAD commit is ready for +release. -Perform some smoke-testing. We have [citgm](https://github.com/nodejs/citgm) for this. You can also manually test important modules from the ecosystem. Remember that node-gyp and npm both take a `--nodedir` flag to point to your local repository so that you can test unreleased versions without needing node-gyp to download headers for you. +Perform some smoke-testing. We have [citgm](https://github.com/nodejs/citgm) for +this. You can also manually test important modules from the ecosystem. Remember +that node-gyp and npm both take a `--nodedir` flag to point to your local +repository so that you can test unreleased versions without needing node-gyp to +download headers for you. ### 7. Produce a Nightly Build _(optional)_ -If there is a reason to produce a test release for the purpose of having others try out installers or specifics of builds, produce a nightly build using **[iojs+release](https://ci-release.nodejs.org/job/iojs+release/)** and wait for it to drop in . Follow the directions and enter a proper length commit SHA, enter a date string, and select "nightly" for "disttype". +If there is a reason to produce a test release for the purpose of having others +try out installers or specifics of builds, produce a nightly build using +**[iojs+release](https://ci-release.nodejs.org/job/iojs+release/)** and wait for +it to drop in . Follow the directions and +enter a proper length commit SHA, enter a date string, and select "nightly" for +"disttype". -This is particularly recommended if there has been recent work relating to the macOS or Windows installers as they are not tested in any way by CI. +This is particularly recommended if there has been recent work relating to the +macOS or Windows installers as they are not tested in any way by CI. ### 8. Produce Release Builds -Use **[iojs+release](https://ci-release.nodejs.org/job/iojs+release/)** to produce release artifacts. Enter the commit that you want to build from and select "release" for "disttype". - -Artifacts from each worker are uploaded to Jenkins and are available if further testing is required. Use this opportunity particularly to test macOS and Windows installers if there are any concerns. Click through to the individual workers for a run to find the artifacts. - -All release workers should achieve "SUCCESS" (and be green, not red). A release with failures should not be promoted as there are likely problems to be investigated. - -You can rebuild the release as many times as you need prior to promoting them if you encounter problems. - -If you have an error on Windows and need to start again, be aware that you'll get immediate failure unless you wait up to 2 minutes for the linker to stop from previous jobs. i.e. if a build fails after having started compiling, that worker will still have a linker process that's running for another couple of minutes which will prevent Jenkins from clearing the workspace to start a new one. This isn't a big deal, it's just a hassle because it'll result in another failed build if you start again! - -ARMv7 takes the longest to compile. Unfortunately ccache isn't as effective on release builds, I think it's because of the additional macro settings that go in to a release build that nullify previous builds. Also most of the release build machines are separate to the test build machines so they don't get any benefit from ongoing compiles between releases. You can expect 1.5 hours for the ARMv7 builder to complete and you should normally wait for this to finish. It is possible to rush a release out if you want and add additional builds later but we normally provide ARMv7 from initial promotion. - -You do not have to wait for the ARMv6 / Raspberry PI builds if they take longer than the others. It is only necessary to have the main Linux (x64 and x86), macOS .pkg and .tar.gz, Windows (x64 and x86) .msi and .exe, source, headers, and docs (both produced currently by an macOS worker). **If you promote builds _before_ ARM builds have finished, you must repeat the promotion step for the ARM builds when they are ready**. If the ARMv6 build failed for some reason you can use the [`iojs-release-arm6-only`](https://ci-release.nodejs.org/job/iojs+release-arm6-only/) build in the release CI to re-run the build only for ARMv6. When launching the build make sure to use the same commit hash as for the original release. +Use **[iojs+release](https://ci-release.nodejs.org/job/iojs+release/)** to +produce release artifacts. Enter the commit that you want to build from and +select "release" for "disttype". + +Artifacts from each worker are uploaded to Jenkins and are available if further +testing is required. Use this opportunity particularly to test macOS and Windows +installers if there are any concerns. Click through to the individual workers +for a run to find the artifacts. + +All release workers should achieve "SUCCESS" (and be green, not red). A release +with failures should not be promoted as there are likely problems to be +investigated. + +You can rebuild the release as many times as you need prior to promoting them if +you encounter problems. + +If you have an error on Windows and need to start again, be aware that you'll +get immediate failure unless you wait up to 2 minutes for the linker to stop +from previous jobs. i.e. if a build fails after having started compiling, that +worker will still have a linker process that's running for another couple of +minutes which will prevent Jenkins from clearing the workspace to start a new +one. This isn't a big deal, it's just a hassle because it'll result in another +failed build if you start again! + +ARMv7 takes the longest to compile. Unfortunately ccache isn't as effective on +release builds, I think it's because of the additional macro settings that go in +to a release build that nullify previous builds. Also most of the release build +machines are separate to the test build machines so they don't get any benefit +from ongoing compiles between releases. You can expect 1.5 hours for the ARMv7 +builder to complete and you should normally wait for this to finish. It is +possible to rush a release out if you want and add additional builds later but +we normally provide ARMv7 from initial promotion. + +You do not have to wait for the ARMv6 / Raspberry PI builds if they take longer +than the others. It is only necessary to have the main Linux (x64 and x86), +macOS .pkg and .tar.gz, Windows (x64 and x86) .msi and .exe, source, headers, +and docs (both produced currently by an macOS worker). **If you promote builds +_before_ ARM builds have finished, you must repeat the promotion step for the +ARM builds when they are ready**. If the ARMv6 build failed for some reason you +can use the +[`iojs-release-arm6-only`](https://ci-release.nodejs.org/job/iojs+release-arm6-only/) +build in the release CI to re-run the build only for ARMv6. When launching the +build make sure to use the same commit hash as for the original release. ### 9. Test the Build -Jenkins collects the artifacts from the builds, allowing you to download and install the new build. Make sure that the build appears correct. Check the version numbers, and perform some basic checks to confirm that all is well with the build before moving forward. +Jenkins collects the artifacts from the builds, allowing you to download and +install the new build. Make sure that the build appears correct. Check the +version numbers, and perform some basic checks to confirm that all is well with +the build before moving forward. ### 10. Tag and Sign the Release Commit -Once you have produced builds that you're happy with, create a new tag. By waiting until this stage to create tags, you can discard a proposed release if something goes wrong or additional commits are required. Once you have created a tag and pushed it to GitHub, you ***should not*** delete and re-tag. If you make a mistake after tagging then you'll have to version-bump and start again and count that tag/version as lost. +Once you have produced builds that you're happy with, create a new tag. By +waiting until this stage to create tags, you can discard a proposed release if +something goes wrong or additional commits are required. Once you have created a +tag and pushed it to GitHub, you ***should not*** delete and re-tag. If you make +a mistake after tagging then you'll have to version-bump and start again and +count that tag/version as lost. -Tag summaries have a predictable format, look at a recent tag to see, `git tag -v v6.0.0`. The message should look something like `2016-04-26 Node.js v6.0.0 (Current) Release`. +Tag summaries have a predictable format, look at a recent tag to see, `git tag +-v v6.0.0`. The message should look something like `2016-04-26 Node.js v6.0.0 +(Current) Release`. Install `git-secure-tag` npm module: @@ -240,9 +360,12 @@ Create a tag using the following command: $ git secure-tag -sm 'YYYY-MM-DD Node.js vx.y.z (Release Type) Release' ``` -The tag **must** be signed using the GPG key that's listed for you on the project README. +The tag **must** be signed using the GPG key that's listed for you on the +project README. -Push the tag to the repo before you promote the builds. If you haven't pushed your tag first, then build promotion won't work properly. Push the tag using the following command: +Push the tag to the repo before you promote the builds. If you haven't pushed +your tag first, then build promotion won't work properly. Push the tag using the +following command: ```console $ git push @@ -263,65 +386,125 @@ Working on vx.y.z # where 'z' is the incremented patch number PR-URL: ``` -This sets up the branch so that nightly builds are produced with the next version number _and_ a pre-release tag. +This sets up the branch so that nightly builds are produced with the next +version number _and_ a pre-release tag. -Merge your release proposal branch into the stable branch that you are releasing from (e.g. `v8.x`), and rebase the corresponding staging branch (`v8.x-staging`) on top of that. +Merge your release proposal branch into the stable branch that you are releasing +from (e.g. `v8.x`), and rebase the corresponding staging branch (`v8.x-staging`) +on top of that. -Cherry-pick the release commit to `master`. After cherry-picking, edit `src/node_version.h` to ensure the version macros contain whatever values were previously on `master`. `NODE_VERSION_IS_RELEASE` should be `0`. +Cherry-pick the release commit to `master`. After cherry-picking, edit +`src/node_version.h` to ensure the version macros contain whatever values were +previously on `master`. `NODE_VERSION_IS_RELEASE` should be `0`. ### 12. Promote and Sign the Release Builds -**It is important that the same individual who signed the release tag be the one to promote the builds as the SHASUMS256.txt file needs to be signed with the same GPG key!** +**It is important that the same individual who signed the release tag be the one +to promote the builds as the SHASUMS256.txt file needs to be signed with the +same GPG key!** -Use `tools/release.sh` to promote and sign the build. When run, it will perform the following actions: +Use `tools/release.sh` to promote and sign the build. When run, it will perform +the following actions: -**a.** Select a GPG key from your private keys. It will use a command similar to: `gpg --list-secret-keys` to list your keys. If you don't have any keys, it will bail. (Why are you releasing? Your tag should be signed!) If you have only one key, it will use that. If you have more than one key it will ask you to select one from the list. Be sure to use the same key that you signed your git tag with. +**a.** Select a GPG key from your private keys. It will use a command similar +to: `gpg --list-secret-keys` to list your keys. If you don't have any keys, it +will bail. (Why are you releasing? Your tag should be signed!) If you have only +one key, it will use that. If you have more than one key it will ask you to +select one from the list. Be sure to use the same key that you signed your git +tag with. -**b.** Log in to the server via SSH and check for releases that can be promoted, along with the list of artifacts. It will use the `dist-promotable` command on the server to find these. You will be asked, for each promotable release, whether you want to proceed. If there is more than one release to promote (there shouldn't be), be sure to only promote the release you are responsible for. +**b.** Log in to the server via SSH and check for releases that can be promoted, +along with the list of artifacts. It will use the `dist-promotable` command on +the server to find these. You will be asked, for each promotable release, +whether you want to proceed. If there is more than one release to promote (there +shouldn't be), be sure to only promote the release you are responsible for. -**c.** Log in to the server via SSH and run the promote script for the given release. The command on the server will be similar to: `dist-promote vx.y.z`. After this step, the release artifacts will be available for download and a SHASUMS256.txt file will be present. The release will still be unsigned, however. +**c.** Log in to the server via SSH and run the promote script for the given +release. The command on the server will be similar to: `dist-promote vx.y.z`. +After this step, the release artifacts will be available for download and a +SHASUMS256.txt file will be present. The release will still be unsigned, +however. -**d.** Use `scp` to download SHASUMS256.txt to a temporary directory on your computer. +**d.** Use `scp` to download SHASUMS256.txt to a temporary directory on your +computer. -**e.** Sign the SHASUMS256.txt file using a command similar to: `gpg --default-key YOURKEY --clearsign /path/to/SHASUMS256.txt`. You will be prompted by GPG for your password. The signed file will be named SHASUMS256.txt.asc. +**e.** Sign the SHASUMS256.txt file using a command similar to: `gpg +--default-key YOURKEY --clearsign /path/to/SHASUMS256.txt`. You will be prompted +by GPG for your password. The signed file will be named SHASUMS256.txt.asc. -**f.** Output an ASCII armored version of your public GPG key using a command similar to: `gpg --default-key YOURKEY --armor --export --output /path/to/SHASUMS256.txt.gpg`. This does not require your password and is mainly a convenience for users, although not the recommended way to get a copy of your key. +**f.** Output an ASCII armored version of your public GPG key using a command +similar to: `gpg --default-key YOURKEY --armor --export --output +/path/to/SHASUMS256.txt.gpg`. This does not require your password and is mainly +a convenience for users, although not the recommended way to get a copy of your +key. -**g.** Upload the SHASUMS256.txt files back to the server into the release directory. +**g.** Upload the SHASUMS256.txt files back to the server into the release +directory. -If you didn't wait for ARM builds in the previous step before promoting the release, you should re-run `tools/release.sh` after the ARM builds have finished. That will move the ARM artifacts into the correct location. You will be prompted to re-sign SHASUMS256.txt. +If you didn't wait for ARM builds in the previous step before promoting the +release, you should re-run `tools/release.sh` after the ARM builds have +finished. That will move the ARM artifacts into the correct location. You will +be prompted to re-sign SHASUMS256.txt. -*Note*: It is possible to only sign a release by running -`./tools/release.sh -s vX.Y.Z`. +*Note*: It is possible to only sign a release by running `./tools/release.sh -s +vX.Y.Z`. ### 13. Check the Release -Your release should be available at `https://nodejs.org/dist/vx.y.z/` and . Check that the appropriate files are in place. You may want to check that the binaries are working as appropriate and have the right internal version strings. Check that the API docs are available at . Check that the release catalog files are correct at and . +Your release should be available at `https://nodejs.org/dist/vx.y.z/` and +. Check that the appropriate files are in +place. You may want to check that the binaries are working as appropriate and +have the right internal version strings. Check that the API docs are available +at . Check that the release catalog files are correct +at and . ### 14. Create a Blog Post -There is an automatic build that is kicked off when you promote new builds, so within a few minutes nodejs.org will be listing your new version as the latest release. However, the blog post is not yet fully automatic. - -Create a new blog post by running the [nodejs.org release-post.js script](https://github.com/nodejs/nodejs.org/blob/master/scripts/release-post.js). This script will use the promoted builds and changelog to generate the post. Run `npm run serve` to preview the post locally before pushing to the [nodejs.org](https://github.com/nodejs/nodejs.org) repo. - -* You can add a short blurb just under the main heading if you want to say something important, otherwise the text should be publication ready. -* The links to the download files won't be complete unless you waited for the ARMv6 builds. Any downloads that are missing will have `*Coming soon*` next to them. It's your responsibility to manually update these later when you have the outstanding builds. -* The SHASUMS256.txt.asc content is at the bottom of the post. When you update the list of tarballs you'll need to copy/paste the new contents of this file to reflect those changes. -* Always use pull-requests on the nodejs.org repo. Be respectful of that working group, but you shouldn't have to wait for PR sign-off. Opening a PR and merging it immediately _should_ be fine. However, please follow the following commit message format: -```console -Blog: vX.Y.Z release post - -Refs: -``` -* Changes to `master` on the nodejs.org repo will trigger a new build of nodejs.org so your changes should appear in a few minutes after pushing. +There is an automatic build that is kicked off when you promote new builds, so +within a few minutes nodejs.org will be listing your new version as the latest +release. However, the blog post is not yet fully automatic. + +Create a new blog post by running the [nodejs.org release-post.js script][]. +This script will use the promoted builds and changelog to generate the post. Run +`npm run serve` to preview the post locally before pushing to the +[nodejs.org](https://github.com/nodejs/nodejs.org) repo. + +- You can add a short blurb just under the main heading if you want to say + something important, otherwise the text should be publication ready. +- The links to the download files won't be complete unless you waited for the + ARMv6 builds. Any downloads that are missing will have `*Coming soon*` next to + them. It's your responsibility to manually update these later when you have + the outstanding builds. +- The SHASUMS256.txt.asc content is at the bottom of the post. When you update + the list of tarballs you'll need to copy/paste the new contents of this file + to reflect those changes. +- Always use pull-requests on the nodejs.org repo. Be respectful of that working + group, but you shouldn't have to wait for PR sign-off. Opening a PR and + merging it immediately _should_ be fine. However, please follow the following + commit message format: + + ```console + Blog: vX.Y.Z release post + + Refs: + ``` + +- Changes to `master` on the nodejs.org repo will trigger a new build of + nodejs.org so your changes should appear in a few minutes after pushing. ### 15. Announce -The nodejs.org website will automatically rebuild and include the new version. To announce the build on Twitter through the official @nodejs account, email [pr@nodejs.org](mailto:pr@nodejs.org) with a message such as: +The nodejs.org website will automatically rebuild and include the new version. +To announce the build on Twitter through the official @nodejs account, email +[pr@nodejs.org](mailto:pr@nodejs.org) with a message such as: -> v5.8.0 of @nodejs is out: https://nodejs.org/en/blog/release/v5.8.0/ … something here about notable changes +> v5.8.0 of @nodejs is out: https://nodejs.org/en/blog/release/v5.8.0/ +> … +> something here about notable changes -To ensure communication goes out with the timing of the blog post, please allow 24 hour prior notice. If known, please include the date and time the release will be shared with the community in the email to coordinate these announcements. +To ensure communication goes out with the timing of the blog post, please allow +24 hour prior notice. If known, please include the date and time the release +will be shared with the community in the email to coordinate these announcements. ### 16. Cleanup @@ -330,3 +513,5 @@ Close your release proposal PR and remove the proposal branch. ### 17. Celebrate _In whatever form you do this..._ + +[nodejs.org release-post.js script]: https://github.com/nodejs/nodejs.org/blob/master/scripts/release-post.js