Skip to content

doc: include security release proposal tutorial #43695

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

doc: include security release proposal tutorial #43695

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 124 additions & 0 deletions doc/contributing/security-release-process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -190,6 +190,130 @@ out a better way, forward the email you receive to
[Security release stewards](https://github.com/nodejs/node/blob/HEAD/doc/contributing/security-release-process.md#security-release-stewards).
If necessary add the next rotation of the steward rotation.

***

## Creating proposal
Copy link
Member

@BethGriggs BethGriggs Jul 6, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm still thinking this content should be in releases.md, with a reference in this file to follow the security release steps. I think maintaining the actual mechanics of release creation in two separate files will be make it more likely for them to become out-of-sync.

We also already have some of the security-specific information in releases.md (such as in https://github.com/nodejs/node/blob/main/doc/contributing/releases.md#5-create-release-commit), so at the moment this would duplicate it.

The actual steps look good though and useful to add though - thanks for writing them down!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@BethGriggs I was kind of thinking the same thing but was happy to defer to what the release team thinks is best. I think having this closer to the other doc for creating releases makes sense to me, and then having a link in this doc to point to that section.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, this document points to the releases.md as a reference too. I've felt a very bad experience when the document tells you to go to another document and then back to the original one. For instance, this document contains:

2. Create a new branch for the release

Then as usual, create the proposal branch:

$ git checkout -b vXX.X.X-proposal

Which could be easily changed to

2. Create a new branch for the release

See: https://github.com/nodejs/node/blob/main/doc/contributing/releases.md#2-create-a-new-branch-for-the-release

However, IMHO it makes the experience very bad and subjective to mistakes, for instance, I'll follow the releases.md in a security release, which might eventually leak sensitive information.

The major problem I see in having two documents is to keep them synced. But, I don't see the releases.md changing too much making the sync hard.


The process to create a proposal for a Security Release is very similar to the
common release lines. The major difference is that the base repository is [`node-private`](https://github.com/nodejs-private/node-private)
instead of [`node`](https://github.com/nodejs/node).

Once the [previous steps](#planning) were completed, you should be able to
create a proposal against `node-private`.

### Step 1 - Sync vXX.x-staging branch

The first step is to make sure that the
`origin`[\[1\]](#glossary)/`vXX.x-staging`[\[2\]](#glossary) branch is updated:

```console
$ git remote -v
origin git@github.com:nodejs-private/node-private.git (fetch)
origin git@github.com:nodejs-private/node-private.git (push)
upstream git@github.com:nodejs/node.git (fetch)
upstream git@github.com:nodejs/node.git (push)
$ git remote update upstream
$ git reset --hard upstream/vXX.x
```

### 2. Create a new branch for the release

Then as usual, create the proposal branch:

```console
$ git checkout -b vXX.X.X-proposal
```

### 3. Land all the PRs on your proposal branch

**Important**: if you are using `git cherry-pick $SHA1` you will need to
manually add the `Reviewed-By` and `PR-URL`
metadata as `git node land` doesn't work on `node-private`.

```console
$ git cherry-pick 1b27a7152309aa87993596f3802d472dcb15f439
$ git commit --amend

# add metadata
$ git push origin vXX.X.X-proposal # IMPORTANT: origin is `node-private` not a public fork
```

### 4. Update `src/node_version.h`

See: [releases.md](./releases.md#3-update-srcnode_versionh)

### 5. Update the changelog

See: [releases.md](./releases.md#4-update-the-changelog)

**Note**: make sure to include the right entry to the `CHANGELOG_Vx.md`.

The new entry should take the following form:

```markdown
<a id="x.y.x"></a>
## YYYY-MM-DD, Version x.y.z (Release Type), @releaser

This is a security release.

### Notable changes

* List interesting changes here
* Particularly changes that are responsible for minor or major version bumps
* Also be sure to look at any changes introduced by dependencies such as npm
* ... and include any notable items from there

### Commits

* Include the full list of commits since the last release here. Do not include "Working on X.Y.Z+1" commits.
```

### 6. Create release commit

The `CHANGELOG.md`, `doc/changelogs/CHANGELOG_Vx.md`, `src/node_version.h`, and
`REPLACEME` changes should be the final commit that will be tagged for the
release. When committing these to git, use the following message format:

```text
YYYY-MM-DD, Version x.y.z (Release Type)
This is a security release.
Notable changes:
* Copy the notable changes list here, reformatted for plain-text
PR-URL: TBD
```

### 7. Propose release on GitHub

Push the release branch to `nodejs-private/node-private`, 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 `main`. 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 the CHANGELOG pasted into the pull request
is long enough that it slows down the GitHub UI, consider pasting the commits
into `<details>` tags or in follow up comments.

If using the `<details>` tag, use the following format:

```markdown
<details>
<summary>Commits</summary>

* Full list of commits...
</details>
```

If you need any additional information about any of the commits, this PR is a
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.

***

[H1 CVE requests]: https://hackerone.com/nodejs/cve_requests
[docker-node]: https://github.com/nodejs/docker-node/issues
[email]: https://groups.google.com/forum/#!forum/nodejs-sec
Expand Down