From 8b8c55df7ed0d388ec41fc9a7197919a9c59c241 Mon Sep 17 00:00:00 2001 From: Beth Griggs Date: Thu, 14 Jul 2022 21:10:15 +0100 Subject: [PATCH] doc: add security release specifics to releases.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Rafael Gonzaga PR-URL: https://github.com/nodejs/node/pull/43835 Reviewed-By: Michaël Zasso Reviewed-By: Rafael Gonzaga Reviewed-By: Richard Lau Reviewed-By: Michael Dawson --- doc/contributing/releases.md | 152 +++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) diff --git a/doc/contributing/releases.md b/doc/contributing/releases.md index f9e239a84ea179..eb03be2a07de0e 100644 --- a/doc/contributing/releases.md +++ b/doc/contributing/releases.md @@ -119,6 +119,8 @@ Notes: * Version strings are listed below as _"vx.y.z"_ or _"x.y.z"_. Substitute for the release version. * Examples will use the fictional release version `1.2.3`. +* When preparing a security release, follow the security steps in the details + sections. ### 0. Pre-release steps @@ -216,6 +218,42 @@ Then, push to the staging branch to keep it up-to-date. $ git push upstream v1.x-staging ``` +
+Security release + +Security releases with private patches need to be prepared in the `nodejs-private` +GitHub organisation. + +Add the `nodejs-private` remote: + +```console +$ git remote add private git@github.com:nodejs-private/node-private.git +``` + +For security releases, we generally try to only include the security patches. +As there may already be commits on the `vN.x-staging` branch, it is preferable +to checkout the `vN.x` branch and build up the release directly in a proposal +branch. + +```console +$ git checkout vN.x +$ git reset --hard upstream/vN.x +``` + +The list of patches to include should be listed in the "Next Security Release" +issue in `nodejs-private`. Ask the security release steward if you're unsure. + +The `git node land` tool does not work with the `nodejs-private` +organisation. To land a PR in Node.js private, use `git cherry-pick` to apply +each commit from the PR. You will also need to manually apply the PR +metadata (`PR-URL`, `Reviewed-by`, etc.) by amending the commit messages. If +known, additionally include `CVE-ID: CVE-XXXX-XXXXX` in the commit metadata. + +**Note**: Do not run CI on the PRs in `nodejs-private` until CI is locked down. +You can integrate the PRs into the proposal without running full CI. + +
+ ### 2. Create a new branch for the release Create a new branch named `vx.y.z-proposal`, off the corresponding staging @@ -305,6 +343,43 @@ $ branch-diff upstream/v1.x v1.2.3-proposal --require-label=notable-change --pla Be sure that the `` tag, as well as the two headings, are not indented at all. +
+Security release + +For security releases, it is necessary to include more detailed information +including which vulnerabilities have been fixed, and any revert flags or +workarounds to revert to the old behaviour. + +You can use the following template as a guide: + +```markdown + +## YYYY-MM-DD, Version x.y.z (Release Type), @releaser + +This is a security release. + +### Notable changes + +* (High|Medium|Low)(CVE-XXXX-XXXXX) +* ... + +### Commits + +* Include the full list of commits since the last release here. Do not include "Working on X.Y.Z+1" commits. +``` + +Alternatively, refer to one of the [previous security release changelog entries](https://github.com/nodejs/node/blob/main/doc/changelogs/CHANGELOG_V17.md#2022-01-10-version-1731-current-bethgriggs) +to get an idea of the structure and level of detail. + +For each fix, use your judgement as to whether a subheading is necessary to +describe the fix in more detail. Much of this information should be able to be +lifted from the "post-release" announcement (should be available in +`nodejs-private`). If the CVE is being fixed in multiple release lines, try to +coordinate the changelog content between the other release so the descriptions +are consistent. + +
+ At the top of 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 it. Follow the existing examples and be sure to add the release to the _top_ @@ -363,6 +438,9 @@ Notable changes: PR-URL: TBD ``` +
+Security release + For security releases, begin the commit message with the phrase `This is a security release.` to allow the [distribution indexer](https://github.com/nodejs/nodejs-dist-indexer) to @@ -380,6 +458,8 @@ Notable changes: PR-URL: TBD ``` +
+ ### 6. Propose release on GitHub Push the release branch to `nodejs/node`, not to your own fork. This allows @@ -410,6 +490,14 @@ good place to @-mention the relevant contributors. After opening the PR, update the release commit to include `PR-URL` metadata and force-push the proposal. +
+Security release + +If there are private security patches, remember to push and open the proposal +in the `nodejs-private` GitHub repository. + +
+ ### 7. Ensure that the release branch is stable Run a **[`node-test-pull-request`](https://ci.nodejs.org/job/node-test-pull-request/)** @@ -425,6 +513,15 @@ purpose. Run it once with the base `vx.x` branch as a reference and with the proposal branch to check if new regressions could be introduced in the ecosystem. +
+Security release + +If there are private security patches, do not run any CI jobs on the proposal +until CI has been locked down. The security steward should be coordinating this +with the Build Working Group. + +
+ ### 8. Produce a nightly build _(optional)_ If there is a reason to produce a test release for the purpose of having others @@ -437,6 +534,13 @@ enter a proper length commit SHA, enter a date string, and select "nightly" for 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. +
+Security release + +Do not produce a release candidate build. + +
+ ### 9. Produce release builds Use **[iojs+release](https://ci-release.nodejs.org/job/iojs+release/)** to @@ -555,6 +659,26 @@ $ git rebase v1.x $ git push upstream v1.x-staging ``` +
+Security release + +For security releases, you can start merging the release in the `nodejs-private` +GitHub organisation in advance by following the same steps: + +```console +$ git checkout v1.x +$ git merge --ff-only v1.2.3-proposal +$ git push private v1.x +$ git checkout v1.x-staging +$ git rebase v1.x +$ git push private v1.x-staging +``` + +Once all releasers are ready, you can push each of the branches to the public +repository. + +
+ ### 13. Cherry-pick the release commit to `main` ```console @@ -585,6 +709,27 @@ $ git push upstream main **Do not** cherry-pick the "Working on vx.y.z" commit to `main`. +
+Security release + +For security releases, you will also need to land the fixes on the `main` +branch (if they apply there). Often, you can just cherry-pick the same commit +that landed in the `current` security release which should already have the +metadata. + +It is useful to first push the patches to `private/main` to check that the +GitHub actions runs pass, before pushing to `upstream/main`: + +```console +$ git checkout main +$ git reset --hard upstream/main +$ git cherry-pick ... # apply the patches which apply to main +$ git push private main # push to private main first run GitHub actions +$ git push upstream main +``` + +
+ ### 14. Push the release tag Push the tag to the repository before you promote the builds. If you @@ -744,6 +889,13 @@ announcements. Ping the IRC ops and the other [Partner Communities][] liaisons. +
+Security release + +Let the security release steward know the releases are available. + +
+ ### 21. Celebrate _In whatever form you do this..._