Update version publishing utilities to handle all versions

This change simplifies the utility by making it always fix all references instead of depending on user defined argument values. Other changes: - Drop semver and @types/semver as it is no longer needed - Update root readme for versioning tasks with npm scripts Signed-off-by: Jeremy Ho <[email protected]>
bcgov · Dec 27, 2024 · 684c44e · 684c44e
1 parent d6d938a
commit 684c44e
Show file tree

Hide file tree

Showing 6 changed files with 73 additions and 54 deletions.
diff --git a/README.md b/README.md
@@ -11,24 +11,31 @@ static website generator.
 ## Directory Structure
 
 ```txt
-.github/                   - PR, Issue templates
+.github/                   - GitHub PR and Issue templates
 .vscode/                   - VSCode environment configurations
 blog/                      - Blog Content Root (Dormant)
 docs/                      - Docs Content Root
 ├── docusaurus/            - Docusaurus Tutorials
 ├── intro/                 - PIES General Information
 ├── spec/                  - PIES Technical Specification
-│   ├── schemas/           - PIES Schema Documentation
-│   ├── types/             - PIES Data Types Documentation
+│   ├── concept/           - PIES Concept Maps
+│   ├── data/              - PIES Data Type Schemas
+│   ├── message/           - PIES Message Type Schemas
+│   ├── resource/          - PIES Resource Type Schemas
 │   └── tags.yaml          - Canonical documentation tags
 ├── src/                   - Docusaurus Source Code
 └── static/                - Site Static Assets
+bcgovpubcode.yml           - BCGov Repository Metadata
 CODE-OF-CONDUCT.md         - Code of Conduct
 COMPLIANCE.yaml            - BCGov PIA/STRA compliance status
 CONTRIBUTING.md            - Contributing Guidelines
+docusaurus.config.ts       - Main Docusaurus configuration
 LICENSE                    - License (Code)
 LICENSE-docs               - License (Documentation)
+renovate.json              - Mend Renovate configuration
 SECURITY.md                - Security Policy and Reporting
+sidebars.ts                - Main Docusaurus sidebar configuration
+versionUtils.mts           - PIES Versioning Utilities
 ```
 
 ## Installation Guide
@@ -43,6 +50,8 @@ SECURITY.md                - Security Policy and Reporting
 npm ci
 ```
 
+This command installs the dependencies as defined by the lockfile.
+
 ### Run Local Development
 
 ```sh
@@ -61,6 +70,19 @@ npm run build
 This command generates static content into the `build` directory and can be
 served using any static contents hosting service.
 
+### Versioning
+
+Releasing a version requires the following actions to be done in order:
+
+1. Run `npm version` with argument `patch`, `minor` or `major` depending on the
+desired outcome (e.g. `npm version minor`).
+2. Run `npm run version` with the semver version to be published (e.g.
+`npm run version 0.1.0`). This will create a new Docusaurus version, and run a
+script to align all the schema references appropriately.
+
+_Note: You may run `npm run postversion` directly in the event you need to
+manually align all the schema references._
+
 ---
 
 ### Deployment Notes
@@ -102,8 +124,8 @@ project you agree to abide by its terms.
 This repository is dual licensed.
 
 - _Software or code_ by the Province of British Columbia is licensed under an
-[AGPL v3 License](./LICENSE)
-[![AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+  [AGPL v3 License](./LICENSE)
+  [![AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 
   ```txt
   NR Permitting Interoperability Exchange Specification
@@ -124,5 +146,5 @@ This repository is dual licensed.
   ```
 
 - _Documentation_ by the Province of British Columbia is licensed under a
-[Creative Commons Attribution 4.0 International License](./LICENSE-docs)
-[![Creative Commons Attribution 4.0 International License](https://i.creativecommons.org/l/by/4.0/80x15.png)](http://creativecommons.org/licenses/by/4.0/)
+  [Creative Commons Attribution 4.0 International License](./LICENSE-docs)
+  [![Creative Commons Attribution 4.0 International License](https://i.creativecommons.org/l/by/4.0/80x15.png)](http://creativecommons.org/licenses/by/4.0/)
diff --git a/bcgovpubcode.yml b/bcgovpubcode.yml
@@ -19,23 +19,23 @@ product_information:
   product_name: Permitting Interoperability Exchange Specification
   product_status: maturing
   product_urls:
-    - https://bcgov.github.io/nr-permit-interoperability-exchange-specification
+    - https://bcgov.github.io/nr-pies
   program_area: Permitting and Data Solutions Branch
 product_technology_information:
   backend_frameworks:
     - name: Docusaurus
-      version: 3.5.2
+      version: 3.6.3
   backend_languages_version:
     - name: TypeScript
-      version: 5.6.3
+      version: 5.7.2
   ci_cd_tools:
     - GitHub-Actions
   frontend_frameworks:
     - name: React
-      version: 18.0.0
+      version: 18.3.1
   frontend_languages:
     - name: TypeScript
-      version: 5.6.3
+      version: 5.7.2
   hosting_platforms:
     - Other
   hosting_platforms_custom: GitHub Pages

diff --git a/docusaurus.config.ts b/docusaurus.config.ts
@@ -101,7 +101,7 @@ const config: Config = {
     },
     docs: {
       sidebar: {
-        autoCollapseCategories: true, // Flip to true when we have more content to help with navigation focus
+        autoCollapseCategories: true,
         hideable: true
       }
     },
@@ -114,6 +114,7 @@ const config: Config = {
         srcDark: 'img/BCID_H_rgb_rev.png'
       },
       items: [
+        // TODO: Uncomment this when we do our first version release
         // {
         //   type: 'docsVersionDropdown',
         //   position: 'left',

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -7,12 +7,14 @@
     "docusaurus": "docusaurus",
     "start": "docusaurus start",
     "build": "docusaurus build",
+    "prebuild": "npm run typecheck",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",
     "serve": "docusaurus serve",
     "version": "docusaurus docs:version",
-    "version:fix": "node --experimental-strip-types ./publish-utils.mts",
+    "postversion": "npm run version:fix",
+    "version:fix": "node --experimental-strip-types ./versionUtils.mts",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
     "typecheck": "tsc"
@@ -35,8 +37,6 @@
     "@docusaurus/module-type-aliases": "3.6.3",
     "@docusaurus/tsconfig": "3.6.3",
     "@docusaurus/types": "3.6.3",
-    "@types/semver": "7.5.8",
-    "semver": "7.6.3",
     "typescript": "5.7.2"
   },
   "browserslist": {

diff --git a/publish-utils.mts → versionUtils.mts b/publish-utils.mts → versionUtils.mts
@@ -1,31 +1,29 @@
 // This script updates all path references to use the right directory
-import {
-  existsSync,
-  readdirSync,
-  readFileSync,
-  statSync,
-  writeFileSync
-} from 'fs';
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'fs';
 import { join } from 'path';
-import { valid } from 'semver';
 
 const SPEC_DIR = 'spec';
+const VERSIONS_FILE = 'versions.json';
 const VERSIONED_DOCS_DIR = 'versioned_docs';
 
 try {
-  const args = process.argv.slice(2);
-  if (!args.length) throw new Error('Missing arguments.');
+  const versions = JSON.parse(
+    readFileSync(VERSIONS_FILE, { encoding: 'utf-8' })
+  );
+  if (!Array.isArray(versions))
+    throw new Error(`File ${VERSIONS_FILE} is not a JSON array.`);
 
-  const version = args[0];
-  if (!valid(version)) throw new Error(`Argument '${version}' is not semver.`);
+  versions.forEach((version: string) => {
+    const working_dir = `${VERSIONED_DOCS_DIR}/version-${version}/${SPEC_DIR}`;
 
-  const working_dir = `${VERSIONED_DOCS_DIR}/version-${version}/${SPEC_DIR}`;
-  if (!existsSync(working_dir))
-    throw new Error(`Directory ${working_dir} does not exist.`);
-
-  const files = walk(working_dir);
-  patch(files, '.mdx', '@site/docs/spec', `@site/${working_dir}`);
-  patch(files, '.schema.json', 'docs/spec', `${working_dir}`);
+    if (!statSync(working_dir, { throwIfNoEntry: false })) {
+      console.warn(`Version directory ${working_dir} does not exist.`);
+    } else {
+      const files = walk(working_dir);
+      patch(files, '.mdx', '@site/docs/spec', `@site/${working_dir}`);
+      patch(files, '.schema.json', 'docs/spec', `${working_dir}`);
+    }
+  });
 } catch (err) {
   console.error(err);
   process.exit(1);
@@ -49,9 +47,11 @@ function patch(files: Array<string>, ext: string, from: string, to: string) {
 
   schemas.forEach((file) => {
     const oldSchema = readFileSync(file, { encoding: 'utf-8' });
-    const newSchema = oldSchema.replaceAll(from, to);
-    writeFileSync(file, newSchema, { encoding: 'utf-8' });
-    console.log(`Patched file ${file}`);
+    if (oldSchema.match(from)) {
+      const newSchema = oldSchema.replaceAll(from, to);
+      writeFileSync(file, newSchema, { encoding: 'utf-8' });
+      console.log(`Patched file ${file}`);
+    }
   });
 }
 
@@ -69,6 +69,7 @@ function walk(dir: string): Array<string> {
   list.forEach((file) => {
     file = join(dir, file);
     const stat = statSync(file);
+
     if (stat && stat.isDirectory()) {
       results = [...results, ...walk(file)];
     } else {