doc: various updates to RELEASING.md

[sxa]

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]

Review requested:

• @nodejs/tsc

[aduh95]

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

[sxa]

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]

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]

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.

[sxa]

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]

Couple of suggestions/notes, but none are blocking.

[ruyadorno]

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.

[sxa]

I'll have a think and aim to make another push with a suggestion later today (unless someone else drafts something first)

[sxa]

I've made another push on this. Let me know what you think. Two things:

• I'm not sure we have a documented process for getting added to the backporters team. Neither the backporting guide or the Release GOVERNANCE.md mention it so I have not included any details of that
• We have perhaps used "publish" and "promote" interchangeably in this document. I'm sticking with "publish" in my latest change but maybe we should be consistent (or maybe there's a reason for the difference in which case let me know if I've used the wrong term :-) )

[aduh95]

I'd stick with promote over publish, that's what the flag is called in NCU, but that can be a follow up

[sxa]

Landed in 6e8a24d

[sxa]

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]

Review requested:

• @nodejs/tsc

[aduh95]

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

[sxa]

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]

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]

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.

[sxa]

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]

Couple of suggestions/notes, but none are blocking.

[ruyadorno]

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.

[sxa]

I'll have a think and aim to make another push with a suggestion later today (unless someone else drafts something first)

[sxa]

I've made another push on this. Let me know what you think. Two things:

• I'm not sure we have a documented process for getting added to the backporters team. Neither the backporting guide or the Release GOVERNANCE.md mention it so I have not included any details of that
• We have perhaps used "publish" and "promote" interchangeably in this document. I'm sticking with "publish" in my latest change but maybe we should be consistent (or maybe there's a reason for the difference in which case let me know if I've used the wrong term :-) )

[aduh95]

I'd stick with promote over publish, that's what the flag is called in NCU, but that can be a follow up

[sxa]

Landed in 6e8a24d

[sxa]

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]

Review requested:

• @nodejs/tsc

[aduh95]

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

[sxa]

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]

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]

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.

[sxa]

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]

Couple of suggestions/notes, but none are blocking.

[ruyadorno]

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.

[sxa]

I'll have a think and aim to make another push with a suggestion later today (unless someone else drafts something first)

[sxa]

I've made another push on this. Let me know what you think. Two things:

• I'm not sure we have a documented process for getting added to the backporters team. Neither the backporting guide or the Release GOVERNANCE.md mention it so I have not included any details of that
• We have perhaps used "publish" and "promote" interchangeably in this document. I'm sticking with "publish" in my latest change but maybe we should be consistent (or maybe there's a reason for the difference in which case let me know if I've used the wrong term :-) )

[aduh95]

I'd stick with promote over publish, that's what the flag is called in NCU, but that can be a follow up

[sxa]

Landed in 6e8a24d

[sxa]

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]

Review requested:

• @nodejs/tsc

[aduh95]

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

[sxa]

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]

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]

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.

[sxa]

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]

Couple of suggestions/notes, but none are blocking.

[ruyadorno]

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.

[sxa]

I'll have a think and aim to make another push with a suggestion later today (unless someone else drafts something first)

[sxa]

I've made another push on this. Let me know what you think. Two things:

• I'm not sure we have a documented process for getting added to the backporters team. Neither the backporting guide or the Release GOVERNANCE.md mention it so I have not included any details of that
• We have perhaps used "publish" and "promote" interchangeably in this document. I'm sticking with "publish" in my latest change but maybe we should be consistent (or maybe there's a reason for the difference in which case let me know if I've used the wrong term :-) )

[aduh95]

I'd stick with promote over publish, that's what the flag is called in NCU, but that can be a follow up

[sxa]

Landed in 6e8a24d

[sxa]

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]

Review requested:

• @nodejs/tsc

[aduh95]

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

[sxa]

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]

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]

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.

[sxa]

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]

Couple of suggestions/notes, but none are blocking.

[ruyadorno]

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.

[sxa]

I'll have a think and aim to make another push with a suggestion later today (unless someone else drafts something first)

[sxa]

I've made another push on this. Let me know what you think. Two things:

• I'm not sure we have a documented process for getting added to the backporters team. Neither the backporting guide or the Release GOVERNANCE.md mention it so I have not included any details of that
• We have perhaps used "publish" and "promote" interchangeably in this document. I'm sticking with "publish" in my latest change but maybe we should be consistent (or maybe there's a reason for the difference in which case let me know if I've used the wrong term :-) )

[aduh95]

I'd stick with promote over publish, that's what the flag is called in NCU, but that can be a follow up

[sxa]

Landed in 6e8a24d

[sxa]

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]

Review requested:

• @nodejs/tsc

[aduh95]

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

[sxa]

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]

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]

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.

[sxa]

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]

Couple of suggestions/notes, but none are blocking.

[ruyadorno]

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.

[sxa]

I'll have a think and aim to make another push with a suggestion later today (unless someone else drafts something first)

[sxa]

I've made another push on this. Let me know what you think. Two things:

• I'm not sure we have a documented process for getting added to the backporters team. Neither the backporting guide or the Release GOVERNANCE.md mention it so I have not included any details of that
• We have perhaps used "publish" and "promote" interchangeably in this document. I'm sticking with "publish" in my latest change but maybe we should be consistent (or maybe there's a reason for the difference in which case let me know if I've used the wrong term :-) )

[aduh95]

I'd stick with promote over publish, that's what the flag is called in NCU, but that can be a follow up

[sxa]

Landed in 6e8a24d

[sxa]

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]

Review requested:

• @nodejs/tsc

[aduh95]

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

[sxa]

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]

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]

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.

[sxa]

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]

Couple of suggestions/notes, but none are blocking.

[ruyadorno]

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.

[sxa]

I'll have a think and aim to make another push with a suggestion later today (unless someone else drafts something first)

[sxa]

I've made another push on this. Let me know what you think. Two things:

• I'm not sure we have a documented process for getting added to the backporters team. Neither the backporting guide or the Release GOVERNANCE.md mention it so I have not included any details of that
• We have perhaps used "publish" and "promote" interchangeably in this document. I'm sticking with "publish" in my latest change but maybe we should be consistent (or maybe there's a reason for the difference in which case let me know if I've used the wrong term :-) )

[aduh95]

I'd stick with promote over publish, that's what the flag is called in NCU, but that can be a follow up

[sxa]

Landed in 6e8a24d

[sxa]

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]

Review requested:

• @nodejs/tsc

[aduh95]

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

[sxa]

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]

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]

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.

[sxa]

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]

Couple of suggestions/notes, but none are blocking.

[ruyadorno]

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.

[sxa]

I'll have a think and aim to make another push with a suggestion later today (unless someone else drafts something first)

[sxa]

I've made another push on this. Let me know what you think. Two things:

• I'm not sure we have a documented process for getting added to the backporters team. Neither the backporting guide or the Release GOVERNANCE.md mention it so I have not included any details of that
• We have perhaps used "publish" and "promote" interchangeably in this document. I'm sticking with "publish" in my latest change but maybe we should be consistent (or maybe there's a reason for the difference in which case let me know if I've used the wrong term :-) )

[aduh95]

I'd stick with promote over publish, that's what the flag is called in NCU, but that can be a follow up

[sxa]

Landed in 6e8a24d