Initial support for release candidates and milestones in release automation

Fixes #21

Author: ryanjbaxter

.github/actions/spring-release-train-project-ready/action.yml

@@ -58,7 +58,22 @@ runs:
           release_repo="spring-cloud/spring-cloud-release"
         fi
 
-        filename="${release_train_version//./_}.properties"
+        # Deliberately identical to releaseTrainVersionToFileName in
+        # update-project-versions/src/index.js, which is the action that reads this same
+        # file a few steps below: a pre-release qualifier is lower-cased, the numeric part
+        # is not. 2026.0.0-M1 -> 2026_0_0-m1.properties, 2026.0.0 -> 2026_0_0.properties.
+        # Upper-casing here would validate one file and stamp from another - invisible for
+        # GA versions, which carry no qualifier at all.
+        # tr rather than bash's ${x,,} or GNU sed's \L, both of which are unavailable in
+        # the bash 3.2 on a developer's Mac and so could not be exercised outside a runner.
+        if [[ "$release_train_version" == *-* ]]; then
+          lowered_qualifier=$(printf '%s' "${release_train_version#*-}" \
+            | tr '[:upper:]' '[:lower:]')
+          normalized="${release_train_version%%-*}-${lowered_qualifier}"
+        else
+          normalized="$release_train_version"
+        fi
+        filename="${normalized//./_}.properties"
         echo "Fetching ${filename} from ${release_repo}@jenkins-releaser-config..."
 
         content=$(gh api "repos/${release_repo}/contents/${filename}?ref=jenkins-releaser-config" \
@@ -121,10 +136,16 @@ runs:
           echo "release-ci-settings.xml not found — skipping."
         fi
 
+    # A milestone or release candidate stamps -M<n>/-RC<n> versions on purpose, and its
+    # dependencies are a mixture of milestone, release-candidate and GA versions. Only
+    # -SNAPSHOT is always wrong, so the milestone half of the check is turned off for a
+    # pre-release. Derived from the version being released rather than taken as an input:
+    # the two can never legitimately disagree.
     - name: Verify no snapshot versions
       uses: ./.github/actions/verify-no-snapshot-versions
       with:
         directory: ${{ inputs.project }}
+        allow-prerelease: ${{ contains(inputs.project-version, '-M') || contains(inputs.project-version, '-RC') }}
 
     - name: Commit and push changes
       shell: bash

.github/actions/verify-no-snapshot-versions/README.md

@@ -35,6 +35,7 @@ Any other key has its value checked only when the value is *shaped* like a versi
 
 | Input | Description | Required | Default |
 |-------|-------------|----------|---------|
+| `allow-prerelease` | Permit `-M<n>` and `-RC<n>` versions. Set when verifying a milestone or release candidate. `-SNAPSHOT` is rejected either way. | No | `false` |
 | `directory` | Root directory of the project to verify | No | `.` |
 | `exclude-patterns` | Newline-separated list of regular expressions. Any file whose absolute path matches one of these patterns is excluded from version checking. | No | See below |
 
@@ -123,11 +124,33 @@ steps:
 
 Any version value matching one of these patterns (case-insensitive) is a violation:
 
-| Pattern | Example |
-|---------|---------|
-| `-SNAPSHOT` | `4.2.0-SNAPSHOT` |
-| `-RC<N>` | `3.3.0-RC1`, `3.3.0-RC2` |
-| `-M<N>` | `2023.0.0-M1`, `4.2.0-M12` |
+| Pattern | Example | Flagged by default | Flagged with `allow-prerelease` |
+|---------|---------|--------------------|---------------------------------|
+| `-SNAPSHOT` | `4.2.0-SNAPSHOT` | Yes | Yes |
+| `-RC<N>` | `3.3.0-RC1`, `3.3.0-RC2` | Yes | No |
+| `-M<N>` | `2023.0.0-M1`, `4.2.0-M12` | Yes | No |
+
+### Milestone and release candidate releases
+
+A GA release must contain nothing but GA versions, which is the default.
+
+A milestone or release candidate is different: it stamps `-M<n>`/`-RC<n>` on the project
+itself, and it depends on the other projects in the train at *their* pre-release versions
+while still depending on GA versions of everything outside it. So a `5.1.0-M1` build
+legitimately contains a mixture of `-M<n>`, `-RC<n>` and plain versions, and the default
+check would report every one of them.
+
+`allow-prerelease: true` relaxes exactly that, and nothing else. `-SNAPSHOT` is still a
+violation, because a snapshot is a moving target that must never be published in any
+release.
+
+This is a blanket allow rather than a match against the specific version being released —
+during the `5.1.0-RC1` release a stale `5.1.0-M1` left somewhere would pass. That is
+deliberate: a pre-release train carries a mixture of phases by design, so there is no
+single correct version to match against.
+
+`spring-release-train-project-ready` sets this automatically from the version it is
+releasing; callers rarely need to pass it by hand.
 
 ## Suppressing Individual Version Checks in pom.xml
 

.github/actions/verify-no-snapshot-versions/__tests__/index.test.js

@@ -58,6 +58,38 @@ describe('isPreRelease', () => {
   });
 });
 
+// ─── isPreRelease with allow-prerelease ──────────────────────────────────────
+// A milestone or release-candidate build legitimately mixes -M<n>, -RC<n> and GA
+// versions, so those are permitted; -SNAPSHOT never is.
+
+describe('isPreRelease with allowPrerelease', () => {
+  it('still rejects -SNAPSHOT', () => {
+    expect(isPreRelease('4.2.0-SNAPSHOT', true)).toBe(true);
+  });
+
+  it('still rejects -SNAPSHOT whatever its casing', () => {
+    expect(isPreRelease('4.2.0-snapshot', true)).toBe(true);
+  });
+
+  it('permits a milestone version', () => {
+    expect(isPreRelease('4.2.0-M1', true)).toBe(false);
+  });
+
+  it('permits a release candidate version', () => {
+    expect(isPreRelease('3.3.0-RC1', true)).toBe(false);
+  });
+
+  it('permits a milestone alongside a release candidate and a GA version', () => {
+    for (const v of ['5.1.0-M1', '5.1.0-RC1', '4.2.3']) {
+      expect(isPreRelease(v, true)).toBe(false);
+    }
+  });
+
+  it('leaves GA versions alone', () => {
+    expect(isPreRelease('4.2.0', true)).toBe(false);
+  });
+});
+
 // ─── looksLikeVersion ────────────────────────────────────────────────────────
 
 describe('looksLikeVersion', () => {

.github/actions/verify-no-snapshot-versions/action.yml

@@ -1,8 +1,16 @@
 name: 'Verify No Snapshot Versions'
-description: 'Verifies that every version in every Maven and Gradle build file in a Spring Cloud project is a release version (no -SNAPSHOT, -RC*, or -M* versions), wherever it is declared'
+description: 'Verifies that every version in every Maven and Gradle build file in a Spring Cloud project is a release version (no -SNAPSHOT, and no -RC*/-M* unless allow-prerelease is set), wherever it is declared'
 author: 'Spring Cloud Team'
 
 inputs:
+  allow-prerelease:
+    description: >
+      Permit -M<n> and -RC<n> versions. Set this when verifying a milestone or release
+      candidate: such a build legitimately carries a mixture of milestone,
+      release-candidate and GA versions, and the default would reject every one of them.
+      -SNAPSHOT is rejected either way.
+    required: false
+    default: 'false'
   directory:
     description: 'Root directory of the project to verify. Defaults to the current working directory.'
     required: false

.github/actions/verify-no-snapshot-versions/dist/index.js

@@ -28229,12 +28229,19 @@ const fs = __nccwpck_require__(9896);
 const path = __nccwpck_require__(6928);
 
 /**
- * Matches pre-release version suffixes that must not appear in a release build:
+ * Matches the one suffix that must never appear in any release build, milestone
+ * and release candidate included:
  *   -SNAPSHOT      (e.g. 4.1.0-SNAPSHOT)
+ */
+const SNAPSHOT_PATTERN = /-SNAPSHOT$/i;
+
+/**
+ * Matches the pre-release suffixes that are forbidden in a GA build but expected
+ * in a milestone or release candidate one:
  *   -RC<N>         (e.g. 3.2.0-RC1)
  *   -M<N>          (e.g. 2023.0.0-M1)
  */
-const PRE_RELEASE_PATTERN = /-SNAPSHOT$|-RC\d+$|-M\d+$/i;
+const MILESTONE_PATTERN = /-(RC|M)\d+$/i;
 
 /**
  * Matches values that are shaped like a version number: an optional leading `v`,
@@ -28254,8 +28261,31 @@ const COORDINATE_ELEMENTS = new Set(['dependency', 'plugin', 'extension']);
 
 const CHECK_OFF_ANNOTATION = '@releaser:version-check-off';
 
-function isPreRelease(version) {
-  return PRE_RELEASE_PATTERN.test(String(version).trim());
+/**
+ * Whether milestone and release-candidate versions are tolerated. Set once from the
+ * action input at the top of run(), and read by isPreRelease below.
+ *
+ * Module state rather than a parameter threaded through checkPomFile, walkPomNode,
+ * checkGradlePropertiesContent and the rest: the flag is a property of the run, not of
+ * any one file, and passing it down eight signatures would obscure them for no gain.
+ * isPreRelease still takes an explicit override so the unit tests need no setup.
+ */
+let allowPrereleaseVersions = false;
+
+/**
+ * True when `version` must not appear in the build being verified.
+ *
+ * -SNAPSHOT always counts. -M<n> and -RC<n> count only when the run is verifying a GA
+ * release: a milestone or release-candidate build legitimately carries a mixture of
+ * milestone, release-candidate and GA versions, and rejecting them would fail every
+ * pre-release the moment it was stamped.
+ *
+ * Exported for unit testing.
+ */
+function isPreRelease(version, allowPrerelease = allowPrereleaseVersions) {
+  const value = String(version).trim();
+  if (SNAPSHOT_PATTERN.test(value)) return true;
+  return !allowPrerelease && MILESTONE_PATTERN.test(value);
 }
 
 /**
@@ -28285,6 +28315,12 @@ async function run() {
   try {
     const directory = path.resolve(core.getInput('directory') || '.');
 
+    allowPrereleaseVersions = core.getBooleanInput('allow-prerelease');
+    if (allowPrereleaseVersions) {
+      core.info('allow-prerelease is set: -M<n> and -RC<n> versions are permitted. ' +
+        '-SNAPSHOT versions are still rejected.');
+    }
+
     if (!fs.existsSync(directory)) {
       core.setFailed(`Directory not found: ${directory}`);
       return;
@@ -28321,16 +28357,23 @@ async function run() {
     core.setOutput('violations', JSON.stringify(allViolations));
 
     if (allViolations.length === 0) {
-      core.info('All versions are release versions. No pre-release versions found.');
+      core.info(allowPrereleaseVersions
+        ? 'No -SNAPSHOT versions found.'
+        : 'All versions are release versions. No pre-release versions found.');
       return;
     }
 
-    core.error(`Found ${allViolations.length} pre-release version(s):`);
+    const noun = allowPrereleaseVersions ? 'SNAPSHOT' : 'pre-release';
+    core.error(`Found ${allViolations.length} ${noun} version(s):`);
     for (const v of allViolations) {
       core.error(`  ${v.file}: ${v.location} = ${v.version}`);
     }
     core.setFailed(
-      `${allViolations.length} pre-release version(s) found. All dependencies must use release versions.`
+      `${allViolations.length} ${noun} version(s) found. ` +
+      (allowPrereleaseVersions
+        ? 'A milestone or release candidate may depend on -M<n> and -RC<n> versions, ' +
+          'but never on a -SNAPSHOT.'
+        : 'All dependencies must use release versions.')
     );
   } catch (error) {
     core.setFailed(`Action failed: ${error.message}`);

.github/actions/verify-no-snapshot-versions/src/index.js

@@ -4,12 +4,19 @@ const fs = require('fs');
 const path = require('path');
 
 /**
- * Matches pre-release version suffixes that must not appear in a release build:
+ * Matches the one suffix that must never appear in any release build, milestone
+ * and release candidate included:
  *   -SNAPSHOT      (e.g. 4.1.0-SNAPSHOT)
+ */
+const SNAPSHOT_PATTERN = /-SNAPSHOT$/i;
+
+/**
+ * Matches the pre-release suffixes that are forbidden in a GA build but expected
+ * in a milestone or release candidate one:
  *   -RC<N>         (e.g. 3.2.0-RC1)
  *   -M<N>          (e.g. 2023.0.0-M1)
  */
-const PRE_RELEASE_PATTERN = /-SNAPSHOT$|-RC\d+$|-M\d+$/i;
+const MILESTONE_PATTERN = /-(RC|M)\d+$/i;
 
 /**
  * Matches values that are shaped like a version number: an optional leading `v`,
@@ -29,8 +36,31 @@ const COORDINATE_ELEMENTS = new Set(['dependency', 'plugin', 'extension']);
 
 const CHECK_OFF_ANNOTATION = '@releaser:version-check-off';
 
-function isPreRelease(version) {
-  return PRE_RELEASE_PATTERN.test(String(version).trim());
+/**
+ * Whether milestone and release-candidate versions are tolerated. Set once from the
+ * action input at the top of run(), and read by isPreRelease below.
+ *
+ * Module state rather than a parameter threaded through checkPomFile, walkPomNode,
+ * checkGradlePropertiesContent and the rest: the flag is a property of the run, not of
+ * any one file, and passing it down eight signatures would obscure them for no gain.
+ * isPreRelease still takes an explicit override so the unit tests need no setup.
+ */
+let allowPrereleaseVersions = false;
+
+/**
+ * True when `version` must not appear in the build being verified.
+ *
+ * -SNAPSHOT always counts. -M<n> and -RC<n> count only when the run is verifying a GA
+ * release: a milestone or release-candidate build legitimately carries a mixture of
+ * milestone, release-candidate and GA versions, and rejecting them would fail every
+ * pre-release the moment it was stamped.
+ *
+ * Exported for unit testing.
+ */
+function isPreRelease(version, allowPrerelease = allowPrereleaseVersions) {
+  const value = String(version).trim();
+  if (SNAPSHOT_PATTERN.test(value)) return true;
+  return !allowPrerelease && MILESTONE_PATTERN.test(value);
 }
 
 /**
@@ -60,6 +90,12 @@ async function run() {
   try {
     const directory = path.resolve(core.getInput('directory') || '.');
 
+    allowPrereleaseVersions = core.getBooleanInput('allow-prerelease');
+    if (allowPrereleaseVersions) {
+      core.info('allow-prerelease is set: -M<n> and -RC<n> versions are permitted. ' +
+        '-SNAPSHOT versions are still rejected.');
+    }
+
     if (!fs.existsSync(directory)) {
       core.setFailed(`Directory not found: ${directory}`);
       return;
@@ -96,16 +132,23 @@ async function run() {
     core.setOutput('violations', JSON.stringify(allViolations));
 
     if (allViolations.length === 0) {
-      core.info('All versions are release versions. No pre-release versions found.');
+      core.info(allowPrereleaseVersions
+        ? 'No -SNAPSHOT versions found.'
+        : 'All versions are release versions. No pre-release versions found.');
       return;
     }
 
-    core.error(`Found ${allViolations.length} pre-release version(s):`);
+    const noun = allowPrereleaseVersions ? 'SNAPSHOT' : 'pre-release';
+    core.error(`Found ${allViolations.length} ${noun} version(s):`);
     for (const v of allViolations) {
       core.error(`  ${v.file}: ${v.location} = ${v.version}`);
     }
     core.setFailed(
-      `${allViolations.length} pre-release version(s) found. All dependencies must use release versions.`
+      `${allViolations.length} ${noun} version(s) found. ` +
+      (allowPrereleaseVersions
+        ? 'A milestone or release candidate may depend on -M<n> and -RC<n> versions, ' +
+          'but never on a -SNAPSHOT.'
+        : 'All dependencies must use release versions.')
     );
   } catch (error) {
     core.setFailed(`Action failed: ${error.message}`);