chore(nx-dev): skip website publish for older minor versions (#26272)

Update the website publish flow to not publish if the current minor is
not the latest version.
Moves the logic into a node script

.github/workflows/publish.yml

@@ -288,10 +288,4 @@ jobs:
       - name: Trigger Docs Release
         # Publish docs only on a full release
         if: ${{ !github.event.release.prerelease }}
-        run: |
-          # The GITHUB_REF_NAME is a full version (i.e. 17.3.2). The branchName will only use the major version number.
-          # We will publish docs to the website branch based on the current tag (i.e. website-17)
-          branchName=website-${GITHUB_REF_NAME%.*.*}
-          # We force recreate the branch in order to always be up to date and avoid merge conflicts within the automated workflow
-          git branch -f $branchName
-          git push -f origin $branchName
+        run: npx ts-node ./scripts/release-docs.ts

docs/README.md

@@ -408,3 +408,22 @@ Embed an Nx Graph visualization that can be panned by the user.
 
 {% /graph %}
 ````
+
+## Publishing Process
+
+There are multiple versions of the `nx.dev` site.
+
+- [canary.nx.dev](https://canary.nx.dev) contains the documentation on the `master` branch
+- [nx.dev](https://nx.dev) contains the documentation as of the latest release of Nx to npm. The main site will not include reference documentation for APIs that have been merged to the codebase, but not yet released to the public.
+- `[version].nx.dev` contains the documentation for that version of Nx. `[version]` in this case is the major version up to the current LTS version of Nx. So [18.nx.dev](https://18.nx.dev) will show the Nx documentation as of the last released version of Nx 18.
+
+When a commit that contains documentation is merged into `master`, it will be immediately published to `canary.nx.dev`. Whenever a new release of Nx is published to npm, that documentation will then be available on the main site.
+
+### Immediately Publishing Time-Sensitive Documentation
+
+If you have a documentation change that should be published immediately, you'll need to create 2 PRs.
+
+1. First, create a PR against `master` in the normal manner.
+2. Your second PR needs to be made against the website branch with the latest major version of Nx. So your second PR can be created against `website-19` if the latest version of Nx is `19.1.0`. Once `website-19` is updated with your changes, the main `nx.dev` site will be updated.
+
+Later, when Nx `19.1.1` is released, `website-19` will be overwritten with whatever is on `master` and the first PR you created will take effect.

scripts/release-docs.ts

@@ -0,0 +1,30 @@
+import { execSync } from 'child_process';
+import { gte, major, maxSatisfying } from 'semver';
+
+// The GITHUB_REF_NAME is a full version (i.e. 17.3.2). The branchName will strip the patch version number.
+// We will publish docs to the website branch based on the current tag (i.e. website-17)
+const currentVersion = process.env.GITHUB_REF_NAME || '';
+console.log(`Comparing ${currentVersion} to npm versions`);
+
+const majorVersion = major(currentVersion);
+const releasedVersions: string[] = JSON.parse(
+  execSync(`npm show nx@^${majorVersion} version --json`).toString()
+);
+
+const latestVersion = maxSatisfying(releasedVersions, `^${majorVersion}`);
+
+console.log(`Found npm versions:\n${releasedVersions.join('\n')}`);
+
+// Publish if the current version is greater than or equal to the latest released version
+
+const branchName = `website-${majorVersion}`;
+if (currentVersion && latestVersion && gte(currentVersion, latestVersion)) {
+  console.log(
+    `Publishing docs site for ${process.env.GITHUB_REF_NAME} to ${branchName}`
+  );
+  // We force recreate the branch in order to always be up to date and avoid merge conflicts within the automated workflow
+  execSync(`git branch -f ${branchName}`);
+  execSync(`git push -f origin ${branchName}`);
+} else {
+  console.log(`Not publishing docs to ${branchName}`);
+}