Apply suggestions from code review

Co-authored-by: Henry Mercer <[email protected]>

Author: nickfyson

.github/actions/release-branches/release-branches.py

@@ -1,5 +1,6 @@
 import argparse
-import os, json
+import json
+import os
 import subprocess
 
 # Name of the remote

.github/actions/release-initialise/action.yml

@@ -1,5 +1,5 @@
 name: 'Prepare release job'
-description: 'Executed preparatory steps before update a release branch'
+description: 'Prepare for updating a release branch'
 
 runs:
   using: "composite"

.github/update-release-branch.py

@@ -317,7 +317,7 @@ def main():
     subprocess.check_output(['npm', 'version', version, '--no-git-tag-version'])
     run_git('add', 'package.json', 'package-lock.json')
 
-    # Migrate the changelog notes from v2 version numbers to v1 version numbers
+    # Migrate the changelog notes from vLatest version numbers to vOlder version numbers
     print(f'Migrating changelog notes from v{source_branch_major_version} to v{target_branch_major_version}')
     subprocess.check_output(['sed', '-i', f's/^## {source_branch_major_version}\./## {target_branch_major_version}./g', 'CHANGELOG.md'])
 

.github/workflows/post-release-mergeback.yml

@@ -1,5 +1,5 @@
 # This workflow runs after a merge to any release branch of the action. It:
-# 1. Tags the merge commit on the release branch that represents the new release with n `vN.x.y`
+# 1. Tags the merge commit on the release branch that represents the new release with an `vN.x.y`
 #    tag
 # 2. Updates the `vN` tag to refer to this merge commit.
 # 3. Iff vN == vLatest, merges any changes from the release back into the main branch.

CONTRIBUTING.md

@@ -99,16 +99,20 @@ We typically deprecate a version of CodeQL when the GitHub Enterprise Server (GH
     - Add a changelog note announcing the new minimum version of CodeQL that is now required.
     - Example PR: https://github.com/github/codeql-action/pull/1907
 
-## Deprecating a CodeQL-Action version (write access required)
+## Deprecating a CodeQL Action version (write access required)
 
-When necessary we maintain multiple versions of the CodeQL action, for example to support older version of NodeJS as required by GHES versions that are still supported. The automated release process opens backport PRs to update older versions once the primary release is merged. Deprecation of older versions of the action will generally happen once a particular older GHES version is no longer supported, and hence we can stop maintainin the action for a particular NodeJS version.
+We sometimes maintain multiple versions of the CodeQL Action to enable customers on older but still supported versions of GitHub Enterprise Server (GHES) to continue to benefit from the latest CodeQL improvements. To accomplish this, the release process automation listens to updates to the release branch for the newest supported version.  When this branch is updated, the release process automatically opens backport PRs to update the release branches for older versions.
 
-The backport process is controlled by setting the minimum version number of the action that is still supported, defined at the in the [release-branches](.github/actions/release-branches/release-branches.py) action. To stop udpating an older version of the action:
+We typically deprecate older versions of the Action once all supported GHES versions are compatible with the version of Node.js we are using on `main`.
 
-1. Notify any users who are still pinned to the `vN` tag of the deprecated version of the action.
+To deprecate an older version of the Action:
+
+1. Notify any users who are still pinned to the `vN` tag of the deprecated version of the Action, giving as much notice as is practical.
    - Add a changelog note announcing the deprecation.
-2. Bump the `OLDEST_SUPPORTED_MAJOR_VERSION` in [release-branches.py](.github/actions/release-branches/release-branches.py)
-3. Merge this change to main and the next release will not backport changes to the deprecated release version.
+   - Implement an Actions warning for customers using the deprecated version.
+1. Wait for the deprecation period to pass.
+1. Upgrade the Actions warning for customers using the deprecated version to a non-fatal error, and mention that this version of the Action is no longer supported. 
+1. Make a PR to bump the `OLDEST_SUPPORTED_MAJOR_VERSION` in [release-branches.py](.github/actions/release-branches/release-branches.py).  Once this PR is merged, the release process will no longer backport changes to the deprecated release version.
 
 ## Resources