ci(release): start a stable release's notes at the previous stable tag

.github/workflows/release.yml

@@ -168,6 +168,16 @@ jobs:
           prerelease=false
           [[ "${version}" == *-* ]] && prerelease=true
           from_ref="${last_tag}"
+          # A stable release's notes cover everything since the previous
+          # stable release, its own candidates included; starting from its
+          # last candidate would leave them nearly empty.
+          if [[ "${prerelease}" == false ]]; then
+            last_stable="$(git tag --list 'v*' --sort=-v:refname \
+              | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n1 || true)"
+            if [[ -n "${last_stable}" ]]; then
+              from_ref="${last_stable}"
+            fi
+          fi
           if [[ -z "${from_ref}" ]]; then
             from_ref="$(git rev-list --max-parents=0 HEAD | tail -n1)"
           fi

scripts/tests/release-workflow.test.mjs

@@ -28,11 +28,16 @@ function validateVersion(tags, version) {
     }
     // Registry fixtures model an unpublished version, without network access.
     writeFileSync(path.join(root, 'curl'), '#!/bin/sh\nexit 22\n', { mode: 0o755 });
-    return spawnSync('bash', ['-c', stepScript('Validate release version')], {
+    const outputsPath = path.join(root, 'outputs');
+    const result = spawnSync('bash', ['-c', stepScript('Validate release version')], {
       cwd: root,
       encoding: 'utf8',
-      env: { ...process.env, PATH: `${root}:${process.env.PATH}`, INPUT_VERSION: version, GITHUB_OUTPUT: path.join(root, 'outputs') },
+      env: { ...process.env, PATH: `${root}:${process.env.PATH}`, INPUT_VERSION: version, GITHUB_OUTPUT: outputsPath },
     });
+    const outputs = result.status === 0
+      ? Object.fromEntries(readFileSync(outputsPath, 'utf8').trim().split('\n').map((line) => line.split('=', 2)))
+      : {};
+    return { ...result, outputs };
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
@@ -49,6 +54,24 @@ test('prereleases cannot follow their already-published stable version', () => {
   assert.match(result.stderr, /not above the latest tag v0.5.2\n/);
 });
 
+test('a stable release starts its notes at the previous stable release, not its candidates', () => {
+  const result = validateVersion(['v0.5.1', 'v0.5.2-rc.1', 'v0.5.2-rc.2'], '0.5.2');
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(result.outputs.from_ref, 'v0.5.1');
+});
+
+test('a release candidate starts its notes at the latest tag', () => {
+  const result = validateVersion(['v0.5.1', 'v0.5.2-rc.1'], '0.5.2-rc.2');
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(result.outputs.from_ref, 'v0.5.2-rc.1');
+});
+
+test('a first stable release with only candidates before it starts at the latest candidate', () => {
+  const result = validateVersion(['v0.1.0-rc.1'], '0.1.0');
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(result.outputs.from_ref, 'v0.1.0-rc.1');
+});
+
 test('prerelease sequencing remains numeric and rejects downgrades', () => {
   for (const [previous, next, passes] of [
     ['0.5.2-rc.2', '0.5.2-rc.10', true],