Skip to content

doc: various updates to RELEASING.md#64198

Open
sxa wants to merge 15 commits into
nodejs:mainfrom
sxa:releasesMDupdates
Open

doc: various updates to RELEASING.md#64198
sxa wants to merge 15 commits into
nodejs:mainfrom
sxa:releasesMDupdates

Conversation

@sxa

@sxa sxa commented Jun 29, 2026

Copy link
Copy Markdown
Member

List of updates based on my recent experience preparing 24.18.0.

If anyone thinks that something in this list shouldn't be here let me know, or if any of the list of things I haven't included should be added (or are not actually correct) then let me know.

  • Clarify permissions needed to be able to prepare a release
  • Add CitGM to the "relevant jenkins jobs" section
  • Clarify GPG key creation process and algorithms
  • Also suggest that GPG keys can be published to ubuntu's keyservers
  • Clarify that signed commits on release branches are required
  • Add note about branch-diff using significant github API credits
  • Explicit note to each section which can be skipped with the new automation

On the last point here, I did consider making those things which can now be done via automation into collapsed sections but since there are already collapsed sections in several of them for security releases I decided against it. Thoughts welcome...

Things I haven't included

A few things from my notes from preparing 24.18.0 that I considered adding but left out:

  • An example of using git bisect to track down a problem after doing the initial large set of cherry-picks. I suspect I'm not the only person with scripts they use, but perhaps we could have something for people to use (or do we already?). I've left anything like this out as it should perhaps be somewhere more generic like the collaborator guide.
for example here is the script I use with `git bisect` script

Not that the taskset is something I add to stop the build taking over my machine by limiting which cores it uses:

 echo -n SXAEC: `date +%T` ': '
 git log --pretty=format:"%h %ad | %s%d [%an]" --graph --date=short | head -1
 rm -rf out
 make clean 
 ./configure
 time taskset -c 0-12 make -j12 V= || exit 1
 time taskset -c 0-12 make test-ci V= CI_JS_SUITES=parallel CI_NATIVE_SUITES=
# time taskset -c 0-12 make test-ci V=
 exit $?
  • A note about the automated workflow chosing a new semver major .0.0 version if it detects a commit with a PR-URL: that was originall semver-major even if it has been patched for the backported such that it isn't semver-major. This will mean having to skip use of the automation.
  • The final commit with the version should NOT have Signed-off by at the end (i.e. don't use -s) otherwise it will fail the lint-release-commit check because the PR-URL is not the last line of the commit.
  • I was tempted to give an example of an awk script to convert the initial branch diff output to the "SHA only" version for feeding to git cherry-pick but it felt safer to just suggest running it again.

Also related: #64070 which was something spotted during my release prep :-)

@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

Review requested:

  • @nodejs/tsc

@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label Jun 29, 2026
@sxa sxa force-pushed the releasesMDupdates branch from 80078b3 to ab638b5 Compare June 29, 2026 16:36
- Clarify permissions needed to be able to prepare a release
- Add CitGM to the "relevant jenkins jobs" section
- Clarify GPG key creation process and algorithms
- Also suggest that GPG keys can be published to ubuntu's keyservers
- Clarify that signed commits on release branches are required
- Add note about branch-diff using significant github API credits
- Explicit comment on each section which can be skipped with automation

Signed-off-by: Stewart X Addison <sxa@ibm.com>
@sxa sxa force-pushed the releasesMDupdates branch from ab638b5 to 41ac2cc Compare June 29, 2026 16:40
Signed-off-by: Stewart X Addison <sxa@ibm.com>
Comment thread doc/contributing/releases.md Outdated
Comment thread doc/contributing/releases.md Outdated
Signed-off-by: Stewart X Addison <sxa@ibm.com>
Comment thread doc/contributing/releases.md Outdated
Comment thread doc/contributing/releases.md
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
Comment thread doc/contributing/releases.md Outdated
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
Comment thread doc/contributing/releases.md Outdated
sxa and others added 2 commits June 29, 2026 18:28
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
Signed-off-by: Stewart X Addison <sxa@ibm.com>
Comment thread doc/contributing/releases.md Outdated
Comment thread doc/contributing/releases.md Outdated
Comment thread doc/contributing/releases.md Outdated
Comment on lines 541 to 552

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This is weird, we either need to roll it back, or edit further

@sxa sxa Jun 29, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Updated - let me know whether it alleviates your concerns.

I wanted to make sure the note about the v prefix was before the examples so it would be less likely to be missed and to clarify before the examples that either sed or perl could be used. I'd be tempted to just leave in the perl example for the selfish reason that it's what I always use although not all UNIX-like systems have perl. sed -i also isn't guaranteed to be there on all OSs (it's not a standard POSIX option) and we can see here we've already had to make the examples OS-specific in once case. Although the chances of any collaborators running on an OS which doesn't have sed -i is prety near zero I'd have thought ;-)

@aduh95 aduh95 Jun 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The issue I have is that and substitute this node version with stands alone awkwardly, when it was integrated in the sentence in the main version.

@sxa sxa Jun 30, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Yep - agreed. I've split it a little so that some of the description is now after the initial grep which I think works better and stops that partial sentence sitting there.

Comment thread doc/contributing/releases.md Outdated
sxa and others added 4 commits June 29, 2026 18:39
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
Signed-off-by: Stewart X Addison <sxa@ibm.com>
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
@sxa sxa self-assigned this Jun 29, 2026
sxa added 3 commits June 30, 2026 10:02
Signed-off-by: Stewart X Addison <sxa@ibm.com>
Signed-off-by: Stewart X Addison <sxa@ibm.com>
Signed-off-by: Stewart X Addison <sxa@ibm.com>
@sxa

sxa commented Jun 30, 2026

Copy link
Copy Markdown
Member Author

Now that Antoine has helped me get a few corrections into the original article to clean up the changes (thank you!) and the linters are happy I'm going to tag @nodejs/releasers to for awareness/reviews from other releasers.

@richardlau richardlau left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Couple of suggestions/notes, but none are blocking.

Comment thread doc/contributing/releases.md
Comment thread doc/contributing/releases.md Outdated
Comment thread doc/contributing/releases.md Outdated
Fixups following new review

Signed-off-by: Stewart X Addison <sxa@ibm.com>
Comment on lines +44 to +47
land things on the staging branches and prepare releases. This is a
prerequisite to being able to prepare releases which is the first step
to becoming a releaser.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

"[They] can […] prepare releases. This is a prerequisite to being able to prepare releases" I think there's a logical fallacy here


Release authorization is given by the Node.js TSC. This is required to
promote a release after it has been prepared. If you are working on
preparing a release for the first time you can do that and have someone else

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

"you can do that" you can do what?

promote a release after it has been prepared. If you are working on
preparing a release for the first time you can do that and have someone else
who is already onboarded promote the release on your behalf. Once
authorized by the TSC, an individual will be require the following:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

"an individual will be require the following" I don't understand this, can we rephrase?

Comment on lines +134 to +142
If you wish to also upload your key to the commonly used Ubuntu keyservers
you can do so with

```bash
gpg --keyserver keyserver.ubuntu.com --send-keys <FINGERPRINT>
```

and check it by switching the server name in the `--recv-keys` operation
list above to the Ubuntu keyserver.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

We should probably link to their docs like we do for OpenPGP.org

Individuals who are Members of the
[backporters team](https://github.com/orgs/nodejs/teams/backporters) can
land things on the staging branches and prepare releases. This is a
prerequisite to being able to prepare releases which is the first step

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Suggested change
prerequisite to being able to prepare releases which is the first step
prerequisite to being able to prepare a release, which is the first step

This makes me realize it would be nice to have a small section clarifying the distinction between "Preparing a Release" and "Publishing a Release" that we could link to here.


and substitute this node version with
The above command will check for the presence of the tags and show you which
files need to be updated. You can then perform the replacements with one of

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
files need to be updated. You can then perform the replacements with one of
files need to be updated. You can then perform the replacements with one of

and substitute this node version with
The above command will check for the presence of the tags and show you which
files need to be updated. You can then perform the replacements with one of
the following commands using either `sed` or `perl`. In these examples

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
the following commands using either `sed` or `perl`. In these examples
the following commands using either `sed` or `perl`. In these examples

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doc Issues and PRs related to the documentations.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants