chore(release): protect latest release channels (#4825)

Author: yaacovCR

.github/CONTRIBUTING.md

@@ -122,7 +122,7 @@ Feel free to reach out via the [graphql-js channel](https://discord.com/channels
 
 ## Release on NPM
 
-Releases on `17.x.x` are managed by local scripts and GitHub Actions:
+Releases on maintained release branches are managed by local scripts and GitHub Actions:
 
 ```bash
 git switch 17.x.x
@@ -149,9 +149,15 @@ npm run release:prepare -- 17.x.x prerelease --preid rc
 ```
 
 When `--preid` is provided, the release script uses it as the npm publish tag.
-Without a prerelease preid, the publish tag is `latest`.
-
-Push `<my_release_branch>`, open a PR from `<my_release_branch>` to `17.x.x`, wait for CI to pass, merge the PR, and then approve the GitHub Actions release workflow.
+Without a prerelease preid, stable releases from the latest major use the npm
+`latest` tag and are marked as the latest GitHub release. Stable releases from
+older maintained majors use an npm `latest-<major>` tag and are explicitly not
+marked as the latest GitHub release. Users can install those older majors with a
+semver specifier, for example `npm install graphql@16`.
+
+Push `<my_release_branch>`, open a PR from `<my_release_branch>` to the target
+release branch, wait for CI to pass, merge the PR, and then approve the GitHub
+Actions release workflow.
 
 ## License
 

.github/workflows/release.yml

@@ -14,6 +14,7 @@ jobs:
       should_publish: ${{ steps.release_metadata.outputs.should_publish }}
       tag: ${{ steps.release_metadata.outputs.tag }}
       dist_tag: ${{ steps.release_metadata.outputs.dist_tag }}
+      latest: ${{ steps.release_metadata.outputs.latest }}
       prerelease: ${{ steps.release_metadata.outputs.prerelease }}
     concurrency:
       group: ${{ github.workflow }}-${{ github.ref_name }}
@@ -47,6 +48,7 @@ jobs:
             "version=\(.version)",
             "tag=\(.tag)",
             "dist_tag=\(.distTag)",
+            "latest=\(.latest)",
             "prerelease=\(.prerelease)",
             "package_spec=\(.packageSpec)",
             "should_publish=\(.shouldPublish)"
@@ -120,11 +122,7 @@ jobs:
       - name: Publish to npm
         working-directory: ./npmDist
         run: |
-          if [ -n "${{ needs.check-publish.outputs.dist_tag }}" ]; then
-            npm publish --provenance --tag "${{ needs.check-publish.outputs.dist_tag }}"
-          else
-            npm publish --provenance
-          fi
+          npm publish --provenance --tag "${{ needs.check-publish.outputs.dist_tag }}"
 
   publish-jsr:
     name: Publish JSR package
@@ -204,8 +202,14 @@ jobs:
               --notes-file "${release_notes_file}" \
               --prerelease
           else
+            latest_flag="--latest=false"
+            if [ "${{ needs.check-publish.outputs.latest }}" = "true" ]; then
+              latest_flag="--latest"
+            fi
+
             gh release create "${tag}" \
               --verify-tag \
               --title "${tag}" \
-              --notes-file "${release_notes_file}"
+              --notes-file "${release_notes_file}" \
+              "${latest_flag}"
           fi

package.json

@@ -73,8 +73,5 @@
     "prettier": "3.8.1",
     "typescript": "6.0.3",
     "typescript-eslint": "8.59.0"
-  },
-  "publishConfig": {
-    "tag": "latest"
   }
 }

resources/build-npm.ts

@@ -14,7 +14,6 @@ import type { PlatformConditionalExports } from './utils.ts';
 import {
   buildCJSDevModeStub,
   buildESMDevModeStub,
-  getPublishConfigTag,
   prettify,
   readPackageJSON,
   readTSConfig,
@@ -66,15 +65,6 @@ async function buildPackage(outDir: string): Promise<void> {
     '*': { '*': [notSupportedTSVersionFile] },
   };
 
-  // TODO: move to integration tests
-  const { version } = packageJSON;
-  const publishTag = getPublishConfigTag(version);
-  assert.equal(
-    packageJSON.publishConfig?.tag,
-    publishTag,
-    'Publish tag and version tag should match!',
-  );
-
   delete packageJSON.type;
   packageJSON.main = 'index.js';
   packageJSON.module = 'index.mjs';

resources/release-metadata.ts

@@ -1,8 +1,7 @@
-import assert from 'node:assert';
-
 import {
-  getPublishConfigTag,
+  getReleaseDistTag,
   git,
+  isLatestReleaseVersion,
   isPrereleaseVersion,
   npm,
   readPackageJSON,
@@ -13,6 +12,7 @@ interface ReleaseMetadata {
   version: string;
   tag: string;
   distTag: string;
+  latest: boolean;
   prerelease: boolean;
   releaseNotes: string;
   packageSpec: string;
@@ -22,19 +22,16 @@ interface ReleaseMetadata {
 
 try {
   const packageJSON = readPackageJSON();
-  const { version, publishConfig } = packageJSON;
+  const { version } = packageJSON;
 
   if (typeof version !== 'string' || version === '') {
     throw new Error('package.json is missing a valid "version" field.');
   }
 
   const tag = `v${version}`;
-  const distTag = getPublishConfigTag(version);
-  assert.equal(
-    publishConfig?.tag,
-    distTag,
-    'Publish tag and version tag should match!',
-  );
+  const latestVersion = npm().view('graphql', 'dist-tags.latest');
+  const distTag = getReleaseDistTag(version, latestVersion);
+  const latest = isLatestReleaseVersion(version, latestVersion);
   const prerelease = isPrereleaseVersion(version);
   const releaseCommitSha = findReleaseCommitSha(version);
   const releaseNotes =
@@ -54,6 +51,7 @@ try {
     version,
     tag,
     distTag,
+    latest,
     prerelease,
     releaseNotes,
     packageSpec,

resources/release-prepare.ts

@@ -1,6 +1,4 @@
-import fs from 'node:fs';
-
-import { getPublishConfigTag, git, npm, readPackageJSON } from './utils.ts';
+import { git, npm, readPackageJSON } from './utils.ts';
 
 let args: ParsedArgs;
 try {
@@ -17,9 +15,6 @@ npm().ci('--ignore-scripts');
 console.log('Bumping package version without creating a tag...');
 npm().version(...args.npmVersionArgs, '--no-git-tag-version');
 
-console.log('Updating publishConfig.tag...');
-updatePublishConfigTag();
-
 console.log('Updating src/version.ts...');
 npm().exec(
   '--',
@@ -101,7 +96,10 @@ function validateBranchState(releaseBranch: string): void {
     throw new Error(
       'Git is in detached HEAD state (not on a local branch). ' +
         'Switch to a local branch based on the release branch first, for example:\n' +
-        `  git switch -c release-${releaseBranch.replace(/[^a-zA-Z0-9._-]/g, '-')} ${releaseBranch}`,
+        `  git switch -c release-${releaseBranch.replace(
+          /[^a-zA-Z0-9._-]/g,
+          '-',
+        )} ${releaseBranch}`,
     );
   }
   if (checkedBranch === releaseBranch) {
@@ -200,15 +198,6 @@ function validateBranchState(releaseBranch: string): void {
   }
 }
 
-function updatePublishConfigTag(): void {
-  const packageJSON = readPackageJSON();
-  packageJSON.publishConfig = {
-    ...packageJSON.publishConfig,
-    tag: getPublishConfigTag(packageJSON.version),
-  };
-  fs.writeFileSync('package.json', JSON.stringify(packageJSON, null, 2) + '\n');
-}
-
 function throwUsage(message: string): never {
   throw new Error(
     `${message}\n` +

resources/utils.ts

@@ -280,29 +280,49 @@ export function buildESMDevModeStub(
   ].join('\n');
 }
 
-export function getPublishConfigTag(version: string): string {
-  return getPrereleaseDistTag(version) ?? 'latest';
+export function getReleaseDistTag(
+  version: string,
+  latestVersion: string,
+): string {
+  const { major, prerelease } = parseSemVer(version);
+  if (prerelease != null) {
+    return prerelease.split('.')[0];
+  }
+
+  return major >= parseSemVer(latestVersion).major
+    ? 'latest'
+    : `latest-${major}`;
+}
+
+export function isLatestReleaseVersion(
+  version: string,
+  latestVersion: string,
+): boolean {
+  const { major, prerelease } = parseSemVer(version);
+  return prerelease == null && major >= parseSemVer(latestVersion).major;
 }
 
 export function isPrereleaseVersion(version: string): boolean {
-  return getPrereleaseDistTag(version) != null;
+  return parseSemVer(version).prerelease != null;
 }
 
-function getPrereleaseDistTag(version: string): string | null {
+function parseSemVer(version: string): {
+  major: number;
+  prerelease: string | null;
+} {
   const versionMatch =
-    /^\d+\.\d+\.\d+(?:-(?<prerelease>[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(
+    /^(?<major>\d+)\.\d+\.\d+(?:-(?<prerelease>[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(
       version,
     );
   if (versionMatch?.groups == null) {
     throw new Error('Version does not match semver spec: ' + version);
   }
 
-  const { prerelease } = versionMatch.groups;
-  if (prerelease == null) {
-    return null;
-  }
-
-  return prerelease.split('.')[0];
+  const { major, prerelease } = versionMatch.groups;
+  return {
+    major: Number(major),
+    prerelease: prerelease ?? null,
+  };
 }
 
 interface PackageJSON {
@@ -317,7 +337,6 @@ interface PackageJSON {
   types?: string;
   typesVersions: { [ranges: string]: { [path: string]: Array<string> } };
   devDependencies?: { [name: string]: string };
-  publishConfig: { tag: string };
 
   // TODO: remove after we drop CJS support
   main?: string;