feat(release): Support immutable retry tags.

Author: cpojer

.github/scripts/release-policy.ts

@@ -19,12 +19,16 @@ export function releasePolicy(
   tag: string,
   packages: ReadonlyArray<{ name: string; version: string }>,
 ): { version: string; npmTag: string } {
+  // Retry metadata identifies a Git release attempt, not a new npm version.
+  // Keep real prereleases in the captured version and in channel selection.
   const match =
-    /^v((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?)$/.exec(
+    /^v((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?)(?:\+retry\.[1-9]\d*)?$/.exec(
       tag,
     );
   if (!match || match[0] !== tag || match[2]?.split('.').some((part) => /^0\d+$/.test(part))) {
-    throw new Error('Release tags must be v followed by an exact semantic version.');
+    throw new Error(
+      'Release tags must be v followed by an exact semantic version, optionally ending in +retry.N (N is a positive integer).',
+    );
   }
   const version = match[1];
   if (UNAVAILABLE_VOID_VERSIONS.has(version)) {
@@ -35,7 +39,9 @@ export function releasePolicy(
   }
   for (const pkg of packages) {
     if (pkg.version !== version) {
-      throw new Error(`${pkg.name}@${pkg.version} does not match release ${tag}.`);
+      throw new Error(
+        `${pkg.name}@${pkg.version} does not match release ${tag}. Retry tags use +retry.N; the base version must still match every package.`,
+      );
     }
   }
   const prefix = match[2]?.split('.')[0];

.github/workflows/publish.yml

@@ -8,12 +8,31 @@ on:
 permissions: {}
 
 jobs:
+  validate-release:
+    name: Validate release tag
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - uses: voidzero-dev/setup-vp@2dec1e33f4ab2c6d5bce1b0c4607961bb1a3f7a1 # v1.12.0
+        with:
+          node-version-file: .node-version
+          run-install: false
+          cache: false
+      - name: Validate package versions and release channel
+        run: node .github/scripts/release-policy.ts
+
   ci:
+    needs: validate-release
     uses: ./.github/workflows/ci.yml
     permissions:
       contents: read
 
   platform-ci:
+    needs: validate-release
     uses: ./.github/workflows/platform-ci.yml
     with:
       require-schema-compat: true
@@ -23,6 +42,7 @@ jobs:
 
   prepublish-test:
     name: Prepublish Test
+    needs: validate-release
     uses: ./.github/workflows/prepublish-test.yml
     with:
       suite: full

docs/guide/platform-development.md

@@ -232,4 +232,33 @@ Publishing requires both SDK CI and platform CI, including the platform unit and
 API integration suites. Release tags also run the Windows SDK checks; a passing
 SDK-only build cannot publish a changed control plane.
 
+### Retrying a Release
+
+To retry a failed release without moving an existing tag, add `+retry.N` to a
+new Git tag, with `N` starting at `1`. Keep the package versions unchanged:
+
+| Git tag                  | Package version | npm channel |
+| ------------------------ | --------------- | ----------- |
+| `v0.21.0`                | `0.21.0`        | `latest`    |
+| `v0.21.0+retry.1`        | `0.21.0`        | `latest`    |
+| `v0.21.0-beta.1+retry.2` | `0.21.0-beta.1` | `beta`      |
+
+For example, when the packages are at `0.21.0`, commit the release fix and tag
+that commit:
+
+```sh
+git tag -a 'v0.21.0+retry.1' -m 'Retry 0.21.0 publication.'
+git push origin 'refs/tags/v0.21.0+retry.1'
+```
+
+The retry suffix belongs only in the Git tag, not in `package.json`. A `-1`
+suffix is a distinct prerelease version, not a retry. Tag and package versions
+are checked before dependency installation and the full CI jobs; retries still
+run the normal release checks.
+
+Retries publish only package versions that are still missing from npm. They
+cannot replace an already-published version. If an earlier attempt partially
+published the release and you changed its package contents, bump the version
+instead of combining different contents under the same version.
+
 For implementation history, use the design archive at `platform/meta/design-docs/README.md`. Its proposals explain earlier decisions; the source and current guides define the supported behavior.

packages/void/test/unit/release-policy.test.ts

@@ -18,12 +18,78 @@ describe('public package release policy', () => {
     ).toEqual({ version, npmTag });
   });
 
+  it.each([
+    ['v0.21.0+retry.1', '0.21.0', 'latest'],
+    ['v0.21.0+retry.27', '0.21.0', 'latest'],
+    ['v0.21.0-beta.1+retry.2', '0.21.0-beta.1', 'beta'],
+    ['v0.21.0-rc.2+retry.1', '0.21.0-rc.2', 'rc'],
+    ['v0.21.0-1+retry.1', '0.21.0-1', 'next'],
+    ['v0.21.0-latest.1+retry.1', '0.21.0-latest.1', 'next'],
+  ])('treats %s as an attempt to publish %s to %s', (tag, version, npmTag) => {
+    expect(
+      releasePolicy(tag, [
+        { name: 'void', version },
+        { name: '@void/platform', version },
+      ]),
+    ).toEqual({ version, npmTag });
+  });
+
+  it.each([
+    'v0.21.0+retry',
+    'v0.21.0+retry.',
+    'v0.21.0+retry.0',
+    'v0.21.0+retry.01',
+    'v0.21.0+retry.-1',
+    'v0.21.0+retry.1.extra',
+    'v0.21.0+retry.1+retry.2',
+    'v0.21.0+Retry.1',
+    'v0.21.0+build.1',
+    'v0.21.0-beta.01+retry.1',
+    'v0.21.0+retry.1\n',
+    'v0.21.0+retry.1\nversion=other',
+  ])('rejects malformed or unrecognized retry metadata: %s', (tag) => {
+    expect(() => releasePolicy(tag, [])).toThrow('optionally ending in +retry.N');
+  });
+
+  it('keeps numeric prereleases distinct from stable release retries', () => {
+    expect(() => releasePolicy('v0.21.0-1', [{ name: 'void', version: '0.21.0' }])).toThrow(
+      'Retry tags use +retry.N',
+    );
+  });
+
+  it.each(['0.21.1', '0.21.0+retry.1'])(
+    'requires retry tags to match the plain package version (%s)',
+    (version) => {
+      expect(() => releasePolicy('v0.21.0+retry.1', [{ name: 'void', version }])).toThrow(
+        'does not match release',
+      );
+    },
+  );
+
+  it('checks every package on a retry, not just the CLI', () => {
+    expect(() =>
+      releasePolicy('v0.21.0+retry.1', [
+        { name: 'void', version: '0.21.0' },
+        { name: '@void/platform', version: '0.20.0' },
+      ]),
+    ).toThrow('@void/platform@0.20.0 does not match');
+  });
+
   it.each(['v0.1.0', 'v3.0.1'])('rejects the unavailable version %s', (tag) => {
     expect(() => releasePolicy(tag, [{ name: 'void', version: tag.slice(1) }])).toThrow(
       'cannot be reused',
     );
   });
 
+  it.each(['v0.1.0+retry.1', 'v3.0.1+retry.2'])(
+    'rejects retrying an unavailable version: %s',
+    (tag) => {
+      expect(() =>
+        releasePolicy(tag, [{ name: 'void', version: tag.slice(1).split('+')[0]! }]),
+      ).toThrow('cannot be reused');
+    },
+  );
+
   it.each(['latest', 'v01.2.3', 'v1.2.3-beta.01', 'v1.2.3\nother=tag', 'v1.2.3\n', 'v1.2.3+build'])(
     'rejects malformed release tag %s',
     (tag) => {
@@ -46,7 +112,23 @@ describe('trusted publishing workflow', () => {
     new URL('../../../../.github/workflows/publish.yml', import.meta.url),
     'utf8',
   );
-  const publishJob = workflow.split('\n  publish:\n')[1]!;
+  function job(name: string): string {
+    const parts = workflow.split(`\n  ${name}:\n`);
+    expect(parts).toHaveLength(2);
+    return parts[1]!.split(/\n {2}[\w-]+:\n/)[0]!;
+  }
+  const publishJob = job('publish');
+
+  it('rejects invalid tags before installing dependencies or running CI', () => {
+    const validation = job('validate-release');
+    expect(validation).toContain('node .github/scripts/release-policy.ts');
+    expect(validation).toContain('run-install: false');
+    expect(validation).toContain('cache: false');
+    expect(validation).not.toContain('id-token: write');
+    for (const name of ['ci', 'platform-ci', 'prepublish-test']) {
+      expect(job(name)).toContain('    needs: validate-release\n');
+    }
+  });
 
   it('grants OIDC permission to the GitHub-hosted release job', () => {
     expect(publishJob).toBeDefined();
@@ -61,6 +143,7 @@ describe('trusted publishing workflow', () => {
     expect(publishJob).toContain(
       'vp pm publish -r --access public --tag "$RELEASE_NPM_TAG" --no-git-checks',
     );
+    expect(publishJob).not.toContain('--force');
   });
 
   it('keeps CI gates and validated stable or prerelease channel selection', () => {