Merge pull request #1864 from finos/improve-release-workflow-and-instructions

Improving release workflow to add version sync guardrail and updating instructions

Author: kriswest

.github/workflows/release.yml

@@ -38,6 +38,9 @@ jobs:
       - name: Build
         run: npm run build
 
+      - name: Verify version consistency across workspaces
+        run: npm run version-check
+
       # Compute prerelease flag & desired dist-tag from top-level package.json version
       - name: Determine prerelease tag
         id: version

CHANGELOG.md

@@ -12,9 +12,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added details of and procedures for resolving fully-qualified appIds and unqualified appIds in the API and Bridging Parts of the Standard. ([#1523](https://github.com/finos/FDC3/pull/1523))
 * Added clarification regarding expected behavior upon repeated calls to `addContextListener` on same or overlapping types (allowed) and `addIntentListener` on same intent (rejected; new error type added). ([#1394](https://github.com/finos/FDC3/pull/1394))
 * Added `clearContext` function and associated `contextClearedEvent` to the `Channel` API, to be able to clear specific or all context types from the channel. ([#1379](https://github.com/finos/FDC3/pull/1379))
+* Added `version-check` script and integrated it into the `syncpack` script and Publish To NPM workflow to prevent version mismatches causing incorrect npm dist-tags. ([#1864](https://github.com/finos/FDC3/pull/1864))
 
 ### Changed
 
+* Updated "Releasing FDC3 to NPM" instructions in README to reflect the current GitHub Actions release workflow. ([#1864](https://github.com/finos/FDC3/pull/1864))
+
 ### Deprecated
 
 ### Fixed

README.md

@@ -107,52 +107,44 @@ For installation and usage instructions, see: <https://fdc3.finos.org/docs/suppo
 
 ### Releasing FDC3 to NPM (for maintainers)
 
-This is a 4-step process:
+Publishing to npm is handled automatically by the [Publish To NPM](.github/workflows/release.yml) GitHub Actions workflow, which is triggered when a GitHub Release is published. The workflow will lint, test and build the project, then publish all public workspace packages to both npmjs.org and GitHub Packages.
+
+The npm dist-tag is determined by the version in the root `package.json`: versions containing a hyphen (e.g. `2.3.0-beta.1`) are published with the `prerelease` tag, while all other versions are published with the `latest` tag.
 
 1.  **Create a release branch**
 
-  Do this locally.  Ensure the branch is named `release/v2.0` (or whatever the next version is).
-  
   ```bash
-  git checkout -b release/v2.0
+  git checkout -b release/v2.3
   ```
-  
-2.  **Update the version numbers in the package.json files**
 
-  It's important that all of the versions of the submodules stay on the same version, and that the references between them are consistent to that version.  To change the version number (say before or after a release) run the following:
+2.  **Update version numbers**
+
+  All workspace versions and the root `package.json` version must match. Update them as follows:
 
   ```bash
-  // first, update version number in package.json
-  npm login
-  npm version <new version from package.json> --workspaces // changes the version number in all submodule package.json files
-  npm run syncpack                          // sycnhronizes version numbers
-  npm up                                    // fixes node_module references
-  npm run build                             // builds all the modules against the new version
+  npm version <new-version> --include-workspace-root --workspaces
+  npm run syncpack   # synchronizes @finos/* dependency versions and verifies consistency
+  npm up             # fixes node_module references
+  npm run build      # builds all modules against the new version
   ```
 
-3.  **Push the branch to publish the packages to npm**
+  The `syncpack` script will automatically run `version-check` to verify that the root version matches all public workspace versions. You can also run `npm run version-check` independently at any time.
+
+3.  **Push the branch and create a PR**
 
   ```bash
   git add .
-  git commit -m "Updated to version vx.x" 
-  git push origin release/v2.0
+  git commit -m "Updated to version v2.3.0"
+  git push origin release/v2.3
   ```
-  
-  This should trigger a GitHub action that will publish the packages to npm.
-
-4.  **Create a PR for merging the release branch.**
 
-  Once the packages are published, create a PR to merge the release branch into the main branch.  You will need other FDC3 maintainers to review and approve the PR.
+  Create a PR to merge the release branch into main. You will need other FDC3 maintainers to review and approve the PR.
 
-5.  **Reset the `latest` NPM Version Tag If Releasing A Prerelease**
+4.  **Create a GitHub Release to publish to npm**
 
-  If you're releasing beta/alpha code, be sure to replace the latest version in NPM like so:
-
-  ```
-  npm dist-tag add @finos/fdc3@2.1.1 latest
-  ```
+  Once the PR is merged, [create a new GitHub Release](https://github.com/finos/FDC3/releases/new) targeting the main branch. Publishing the release will trigger the workflow, which will publish all packages to npm and GitHub Packages.
 
-  You will need support from help@finos.org for this step.
+  The workflow also runs a version consistency check before publishing — if the root version doesn't match the workspace versions, the workflow will fail before any packages are published.
 
 ### Releasing the FDC3 Website (for maintainers)
 

package.json

@@ -39,7 +39,8 @@
     "merge": "istanbul-merge --out coverage/complete.json packages/fdc3-standard/coverage/coverage-final.json packages/fdc3-get-agent/coverage/coverage-final.json packages/fdc3-agent-proxy/coverage/coverage-final.json toolbox/fdc3-for-web/fdc3-web-impl/coverage/coverage-final.json",
     "report": "nyc report --reporter json-summary --report-dir nyc-coverage-report --exclude-after-remap false --temp-dir coverage",
     "lint": "npm run lint --workspaces --if-present",
-    "syncpack": "npm exec syncpack -- fix --dependencies \"@finos/*\"",
+    "syncpack": "npm exec syncpack -- fix --dependencies \"@finos/*\" && npm run version-check",
+    "version-check": "node scripts/version-check.js",
     "dev": "concurrently \"cd toolbox/fdc3-conformance && npm run dev\" \"cd toolbox/fdc3-workbench && npm run dev\" \"cd toolbox/fdc3-for-web/reference-ui && npm run dev\" \"cd toolbox/fdc3-for-web/demo && npm run dev\"",
     "prepare": "husky"
   },

scripts/version-check.js

@@ -0,0 +1,21 @@
+const fs = require('fs');
+
+const root = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+const workspaces = root.workspaces || [];
+
+const mismatched = workspaces
+  .map(dir => ({
+    dir,
+    ...JSON.parse(fs.readFileSync(`${dir}/package.json`, 'utf8')),
+  }))
+  .filter(pkg => !pkg.private && pkg.version !== root.version);
+
+if (mismatched.length) {
+  console.error(
+    `ERROR: Root version (${root.version}) does not match:\n` +
+      mismatched.map(p => `  ${p.dir}: ${p.version}`).join('\n')
+  );
+  process.exit(1);
+}
+
+console.log(`All public workspace versions match root: ${root.version}`);