Add warning message for non-stable releases

Automatically add a message to warn people not to put
non-stable releases e.g. 6.2.0-beta.0 into production.

Author: NickColley

shared/github-scripts/changelog-release-helper.mjs

@@ -17,7 +17,8 @@ const processingErrorMessage =
  */
 export function updateChangelog(newVersion, previousVersion) {
   // Skip the entire function if the release version is internal eg: 5.1.0-internal.0
-  if (versionIsAPrerelease(newVersion)) {
+  const newVersionIsAPrelease = versionIsAPrerelease(newVersion)
+  if (newVersionIsAPrelease) {
     const identifier = getPrereleaseIdentifier(newVersion)
 
     if (identifier === 'internal') {
@@ -42,7 +43,18 @@ export function updateChangelog(newVersion, previousVersion) {
   }
   const newVersionTitle = `## v${newVersion} (${convertIncTypeWord(versionDiff, newVersion, true, changelogLines[previousReleaseLineIndex])} release)`
 
-  changelogLines.splice(startIndex + 1, 0, '', newVersionTitle)
+  const newLines = [newVersionTitle]
+  if (newVersionIsAPrelease) {
+    newLines.push(
+      `> [!WARNING]`,
+      `> Do not use in production.`,
+      `> Use this release to prepare for the changes coming in version \`${removePrereleaseFlag(newVersion)}\`.`
+    )
+  }
+
+  // Inject the new lines while replacing the unreleased heading.
+  changelogLines.splice(startIndex + 1, 0, '', ...newLines)
+
   writeFileSync('./CHANGELOG.md', changelogLines.join('\n'))
 }
 
@@ -262,3 +274,15 @@ function convertIncTypeWord(
     ? `${rewordedIncType.charAt(0).toUpperCase()}${rewordedIncType.slice(1)}`
     : rewordedIncType
 }
+
+/**
+ * Remove any pre-release flag from a version e.g. 1.0.0-alpha -> 1.0.0
+ *
+ * @param {string} version - version number
+ * @returns {string} - version number without any pre-release flag
+ */
+function removePrereleaseFlag(version) {
+  const parsedVersion = semver.parse(version)
+  parsedVersion.prerelease = []
+  return parsedVersion.format()
+}

shared/github-scripts/changelog-release-helper.unit.test.mjs

@@ -1,5 +1,7 @@
 import fs from 'fs'
 
+import { outdent } from 'outdent'
+
 import {
   updateChangelog,
   generateReleaseNotes
@@ -55,6 +57,47 @@ describe('Changelog release helper', () => {
       )
     })
 
+    it('displays a warning to not use non-stable releases in production', () => {
+      jest.mocked(fs.readFileSync).mockReturnValue(`
+        ## Unreleased
+
+        ### Fixes
+
+        Bing bong
+
+        ## v3.1.0-beta.0 (Beta feature release)
+      `)
+
+      updateChangelog('3.1.0-beta.1', '3.1.0-beta.0')
+      expect(fs.writeFileSync).toHaveBeenCalledWith(
+        './CHANGELOG.md',
+        expect.stringContaining(outdent`
+          ## v3.1.0-beta.1 (Beta feature release)
+          > [!WARNING]
+          > Do not use in production.
+          > Use this release to prepare for the changes coming in version \`3.1.0\`.
+        `)
+      )
+    })
+
+    it('does not display a warning when the change is a stable release', () => {
+      jest.mocked(fs.readFileSync).mockReturnValue(`
+        ## Unreleased
+
+        ### Fixes
+
+        Bing bong
+
+        ## v3.1.0 (Beta feature release)
+      `)
+
+      updateChangelog('3.1.1', '3.1.0')
+      expect(fs.writeFileSync).not.toHaveBeenCalledWith(
+        './CHANGELOG.md',
+        expect.stringContaining('> [!WARNING]')
+      )
+    })
+
     it('does not change the changelog if the provided version is an internal pre-release', () => {
       const consoleLogSpy = jest.spyOn(console, 'log')