From 684c44e2346f9af70a4c20d1e81dd468ae9405af Mon Sep 17 00:00:00 2001 From: Jeremy Ho Date: Fri, 27 Dec 2024 12:38:03 -0800 Subject: [PATCH] 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 --- README.md | 36 ++++++++++++++++----- bcgovpubcode.yml | 10 +++--- docusaurus.config.ts | 3 +- package-lock.json | 27 +++++++--------- package.json | 6 ++-- publish-utils.mts => versionUtils.mts | 45 ++++++++++++++------------- 6 files changed, 73 insertions(+), 54 deletions(-) rename publish-utils.mts => versionUtils.mts (59%) diff --git a/README.md b/README.md index aa09f3b..d7467e3 100644 --- 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 index 7572f88..0e6b927 100644 --- 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 index d928f6a..0e6e024 100644 --- 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 index 081e080..b7b7e15 100644 --- a/package-lock.json +++ b/package-lock.json @@ -26,8 +26,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" }, "engines": { @@ -6003,13 +6001,6 @@ "@types/node": "*" } }, - "node_modules/@types/semver": { - "version": "7.5.8", - "resolved": "https://registry.npmjs.org/@types/semver/-/semver-7.5.8.tgz", - "integrity": "sha512-I8EUhyrgfLrcTkzV3TSsGyl1tSuPrEDzr0yd5m90UgNxQkyDXULk3b6MlQqTCpZpNtWe1K0hzclnZkTcLBe2UQ==", - "dev": true, - "license": "MIT" - }, "node_modules/@types/send": { "version": "0.17.4", "resolved": "https://registry.npmjs.org/@types/send/-/send-0.17.4.tgz", @@ -9780,9 +9771,9 @@ } }, "node_modules/express": { - "version": "4.21.1", - "resolved": "https://registry.npmjs.org/express/-/express-4.21.1.tgz", - "integrity": "sha512-YSFlK1Ee0/GC8QaO91tHcDxJiE/X4FbpAyQWkxAvG6AXCuR65YzK8ua6D9hvi/TzUfZMpc+BwuM1IPw8fmQBiQ==", + "version": "4.21.2", + "resolved": "https://registry.npmjs.org/express/-/express-4.21.2.tgz", + "integrity": "sha512-28HqgMZAmih1Czt9ny7qr6ek2qddF4FclbMzwhCREB6OFfH+rXAnuNCwo1/wFvrtbgsQDb4kSbX9de9lFbrXnA==", "license": "MIT", "dependencies": { "accepts": "~1.3.8", @@ -9804,7 +9795,7 @@ "methods": "~1.1.2", "on-finished": "2.4.1", "parseurl": "~1.3.3", - "path-to-regexp": "0.1.10", + "path-to-regexp": "0.1.12", "proxy-addr": "~2.0.7", "qs": "6.13.0", "range-parser": "~1.2.1", @@ -9819,6 +9810,10 @@ }, "engines": { "node": ">= 0.10.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" } }, "node_modules/express/node_modules/content-disposition": { @@ -9849,9 +9844,9 @@ "license": "MIT" }, "node_modules/express/node_modules/path-to-regexp": { - "version": "0.1.10", - "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.10.tgz", - "integrity": "sha512-7lf7qcQidTku0Gu3YDPc8DJ1q7OOucfa/BSsIwjuh56VU7katFvuM8hULfkwB3Fns/rsVF7PwPKVw1sl5KQS9w==", + "version": "0.1.12", + "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.12.tgz", + "integrity": "sha512-RA1GjUVMnvYFxuqovrEqZoxxW5NUZqbwKtYz/Tt7nXerk0LbLblQmrsgdeOxV5SFHf0UDggjS/bSeOZwt1pmEQ==", "license": "MIT" }, "node_modules/express/node_modules/range-parser": { diff --git a/package.json b/package.json index be78ec6..b6cd896 100644 --- 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 b/versionUtils.mts similarity index 59% rename from publish-utils.mts rename to versionUtils.mts index 3ee5721..d916ebf 100644 --- a/publish-utils.mts +++ b/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, 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 { list.forEach((file) => { file = join(dir, file); const stat = statSync(file); + if (stat && stat.isDirectory()) { results = [...results, ...walk(file)]; } else {