doc: include updating release optional step

PR-URL: #46089 Reviewed-By: Richard Lau <[email protected]> Reviewed-By: Ruy Adorno <[email protected]> Reviewed-By: Beth Griggs <[email protected]>
nodejs · Jan 25, 2023 · a7174a3 · a7174a3
1 parent 9d43491
commit a7174a3
Showing 1 changed file with 45 additions and 0 deletions.
diff --git a/doc/contributing/releases.md b/doc/contributing/releases.md
@@ -20,6 +20,7 @@ official release builds for Node.js, hosted on <https://nodejs.org/>.
   * [5. Create release commit](#5-create-release-commit)
   * [6. Propose release on GitHub](#6-propose-release-on-github)
   * [7. Ensure that the release branch is stable](#7-ensure-that-the-release-branch-is-stable)
+    * [7.1 Updating the release _(optional)_](#7-1-updating-the-release-optional)
   * [8. Produce a nightly build _(optional)_](#8-produce-a-nightly-build-optional)
   * [9. Produce release builds](#9-produce-release-builds)
   * [10. Test the build](#10-test-the-build)
@@ -545,6 +546,50 @@ with the Build Working Group.
 
 </details>
 
+#### 7.1 Updating the release _(optional)_
+
+Sometimes a release might be deferred to the subsequent day due to several
+conditions:
+
+* Unstable CI
+* Late CI completion
+
+And when it happens, the CHANGELOG\_Vx and the commit metadata needs to be
+updated according to the new target date.
+
+However, if it's just the changelog/commit message that has changed since the
+last CI execution, there's no need to rerun CI, V8, or CITGM workflows.
+The PR still needs a clean GitHub action run, and the original CI, V8, and
+CITGM run should be in a visible comment.
+
+There are some cases when a commit needs to be dropped or adjusted,
+consider using the following approach:
+
+1. Update staging
+
+```console
+$ git checkout v1.x-staging
+$ git rebase -i $HASH_PREVIOUS_BAD_COMMIT
+... drop or edit the bad commit(s)
+$ git push -f upstream v1.x-staging
+```
+
+2. Rebase the proposal against the updated staging branch
+
+```console
+$ git checkout v1.2.3-proposal
+$ git checkout -b v1.2.3-proposal-tmp
+$ git checkout v1.2.3-proposal
+
+$ git reset --hard upstream/v1.x-staging
+$ git cherry-pick v1.2.3-proposal-tmp
+```
+
+Note the `tmp` branch was created just to save the release commit.
+
+3. Re-run `changelog-maker` and update the CHANGELOG\_Vx to include the new
+   Git SHAs. Remember to update the commit message if applicable.
+
 ### 8. Produce a nightly build _(optional)_
 
 If there is a reason to produce a test release for the purpose of having others