diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 3574c3599..ff34d24fd 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,6 +13,6 @@ Describe the way your implementation works or what design decisions you made if Make sure you - [ ] :book: have read the [contribution guidelines](https://github.com/mermaid-js/mermaid/blob/develop/CONTRIBUTING.md) -- [ ] :computer: have added unit/e2e tests (if appropriate) -- [ ] :notebook: have added documentation (if appropriate) +- [ ] :computer: have added necessary unit/e2e tests. +- [ ] :notebook: have added documentation. Make sure [`MERMAID_RELEASE_VERSION`](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/docs/community/development.md#3-update-documentation) is used for all new features. - [ ] :bookmark: targeted `develop` branch diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index b25ff89cc..152b177ae 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -1,6 +1,10 @@ name: Build Vitepress docs on: + push: + branches: + - master + - release/* pull_request: merge_group: @@ -25,5 +29,9 @@ jobs: - name: Install Packages run: pnpm install --frozen-lockfile + - name: Verify release verion + if: ${{ github.event_name == 'push' && (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/heads/release')) }} + run: pnpm --filter mermaid run docs:verify-version + - name: Run Build run: pnpm --filter mermaid run docs:build:vitepress diff --git a/.vscode/launch.json b/.vscode/launch.json index 83b80fa40..dc5ec94a1 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -17,7 +17,7 @@ "name": "Docs generation", "type": "node", "request": "launch", - "args": ["src/docs.mts"], + "args": ["scripts/docs.cli.mts"], "runtimeArgs": ["--loader", "ts-node/esm"], "cwd": "${workspaceRoot}/packages/mermaid", "skipFiles": ["/**", "**/node_modules/**"], diff --git a/docs/community/development.md b/docs/community/development.md index 90f728e15..0634759f5 100644 --- a/docs/community/development.md +++ b/docs/community/development.md @@ -223,6 +223,9 @@ If the users have no way to know that things have changed, then you haven't real Likewise, if users don't know that there is a new feature that you've implemented, it will forever remain unknown and unused. The documentation has to be updated to users know that things have changed and added! +If you are adding a new feature, add `(v+)` in the title or description. It will be replaced automatically with the current version number when the release happens. + +eg: `# Feature Name (v+)` We know it can sometimes be hard to code _and_ write user documentation. diff --git a/packages/mermaid/package.json b/packages/mermaid/package.json index d04083baa..9a1f34676 100644 --- a/packages/mermaid/package.json +++ b/packages/mermaid/package.json @@ -25,14 +25,16 @@ "scripts": { "clean": "rimraf dist", "docs:code": "typedoc src/defaultConfig.ts src/config.ts src/mermaidAPI.ts && prettier --write ./src/docs/config/setup", - "docs:build": "rimraf ../../docs && pnpm docs:spellcheck && pnpm docs:code && ts-node-esm src/docs.mts", - "docs:verify": "pnpm docs:spellcheck && pnpm docs:code && ts-node-esm src/docs.mts --verify", - "docs:pre:vitepress": "pnpm --filter ./src/docs prefetch && rimraf src/vitepress && pnpm docs:code && ts-node-esm src/docs.mts --vitepress && pnpm --filter ./src/vitepress install --no-frozen-lockfile --ignore-scripts", + "docs:build": "rimraf ../../docs && pnpm docs:spellcheck && pnpm docs:code && ts-node-esm scripts/docs.cli.mts", + "docs:verify": "pnpm docs:spellcheck && pnpm docs:code && ts-node-esm scripts/docs.cli.mts --verify", + "docs:pre:vitepress": "pnpm --filter ./src/docs prefetch && rimraf src/vitepress && pnpm docs:code && ts-node-esm scripts/docs.cli.mts --vitepress && pnpm --filter ./src/vitepress install --no-frozen-lockfile --ignore-scripts", "docs:build:vitepress": "pnpm docs:pre:vitepress && (cd src/vitepress && pnpm run build) && cpy --flat src/docs/landing/ ./src/vitepress/.vitepress/dist/landing", - "docs:dev": "pnpm docs:pre:vitepress && concurrently \"pnpm --filter ./src/vitepress dev\" \"ts-node-esm src/docs.mts --watch --vitepress\"", - "docs:dev:docker": "pnpm docs:pre:vitepress && concurrently \"pnpm --filter ./src/vitepress dev:docker\" \"ts-node-esm src/docs.mts --watch --vitepress\"", + "docs:dev": "pnpm docs:pre:vitepress && concurrently \"pnpm --filter ./src/vitepress dev\" \"ts-node-esm scripts/docs.cli.mts --watch --vitepress\"", + "docs:dev:docker": "pnpm docs:pre:vitepress && concurrently \"pnpm --filter ./src/vitepress dev:docker\" \"ts-node-esm scripts/docs.cli.mts --watch --vitepress\"", "docs:serve": "pnpm docs:build:vitepress && vitepress serve src/vitepress", "docs:spellcheck": "cspell --config ../../cSpell.json \"src/docs/**/*.md\"", + "docs:release-version": "ts-node-esm scripts/update-release-version.mts", + "docs:verify-version": "ts-node-esm scripts/update-release-version.mts --verify", "types:build-config": "ts-node-esm --transpileOnly scripts/create-types-from-json-schema.mts", "types:verify-config": "ts-node-esm scripts/create-types-from-json-schema.mts --verify", "release": "pnpm build", diff --git a/packages/mermaid/scripts/docs.cli.mts b/packages/mermaid/scripts/docs.cli.mts new file mode 100644 index 000000000..067eec1c5 --- /dev/null +++ b/packages/mermaid/scripts/docs.cli.mts @@ -0,0 +1,3 @@ +import { processDocs } from './docs.mjs'; + +void processDocs(); diff --git a/packages/mermaid/src/docs.mts b/packages/mermaid/scripts/docs.mts similarity index 97% rename from packages/mermaid/src/docs.mts rename to packages/mermaid/scripts/docs.mts index f62c44f07..3689cb68b 100644 --- a/packages/mermaid/src/docs.mts +++ b/packages/mermaid/scripts/docs.mts @@ -27,8 +27,6 @@ * get their absolute paths. Ensures that the location of those 2 directories is not dependent on * where this file resides. * - * @todo Write a test file for this. (Will need to be able to deal .mts file. Jest has trouble with - * it.) */ // @ts-ignore: we're importing internal jsonschema2md functions import { default as schemaLoader } from '@adobe/jsonschema2md/lib/schemaProxy.js'; @@ -55,9 +53,9 @@ import mm from 'micromatch'; import flatmap from 'unist-util-flatmap'; import { visit } from 'unist-util-visit'; -const MERMAID_MAJOR_VERSION = ( - JSON.parse(readFileSync('../mermaid/package.json', 'utf8')).version as string -).split('.')[0]; +export const MERMAID_RELEASE_VERSION = JSON.parse(readFileSync('../mermaid/package.json', 'utf8')) + .version as string; +const MERMAID_MAJOR_VERSION = MERMAID_RELEASE_VERSION.split('.')[0]; const CDN_URL = 'https://cdn.jsdelivr.net/npm'; // 'https://unpkg.com'; const MERMAID_KEYWORD = 'mermaid'; @@ -80,7 +78,7 @@ const vitepress: boolean = process.argv.includes('--vitepress'); const noHeader: boolean = process.argv.includes('--noHeader') || vitepress; // These paths are from the root of the mono-repo, not from the mermaid subdirectory -const SOURCE_DOCS_DIR = 'src/docs'; +export const SOURCE_DOCS_DIR = 'src/docs'; const FINAL_DOCS_DIR = vitepress ? 'src/vitepress' : '../../docs'; const LOGMSG_TRANSFORMED = 'transformed'; @@ -167,7 +165,7 @@ const copyTransformedContents = (filename: string, doCopy = false, transformedCo logWasOrShouldBeTransformed(fileInFinalDocDir, doCopy); }; -const readSyncedUTF8file = (filename: string): string => { +export const readSyncedUTF8file = (filename: string): string => { return readFileSync(filename, 'utf8'); }; @@ -360,7 +358,7 @@ const transformMarkdown = (file: string) => { /** * Transforms the given JSON Schema into Markdown documentation */ -async function transormJsonSchema(file: string) { +async function transformJsonSchema(file: string) { const yamlContents = readSyncedUTF8file(file); const jsonSchema = load(yamlContents, { filename: file, @@ -506,7 +504,7 @@ const transformHtml = (filename: string) => { copyTransformedContents(filename, !verifyOnly, formattedHTML); }; -const getGlobs = (globs: string[]): string[] => { +export const getGlobs = (globs: string[]): string[] => { globs.push('!**/dist/**', '!**/redirect.spec.ts', '!**/landing/**', '!**/node_modules/**'); if (!vitepress) { globs.push( @@ -520,12 +518,12 @@ const getGlobs = (globs: string[]): string[] => { return globs; }; -const getFilesFromGlobs = async (globs: string[]): Promise => { +export const getFilesFromGlobs = async (globs: string[]): Promise => { return await globby(globs, { dot: true }); }; /** Main method (entry point) */ -const main = async () => { +export const processDocs = async () => { if (verifyOnly) { console.log('Verifying that all files are in sync with the source files'); } @@ -535,7 +533,7 @@ const main = async () => { if (vitepress) { console.log(`${action} 1 .schema.yaml file`); - await transormJsonSchema('src/schemas/config.schema.yaml'); + await transformJsonSchema('src/schemas/config.schema.yaml'); } else { // skip because this creates so many Markdown files that it lags git console.log('Skipping 1 .schema.yaml file'); @@ -603,5 +601,3 @@ const main = async () => { }); } }; - -void main(); diff --git a/packages/mermaid/src/docs.spec.ts b/packages/mermaid/scripts/docs.spec.ts similarity index 100% rename from packages/mermaid/src/docs.spec.ts rename to packages/mermaid/scripts/docs.spec.ts diff --git a/packages/mermaid/scripts/update-release-version.mts b/packages/mermaid/scripts/update-release-version.mts new file mode 100644 index 000000000..7f292f21b --- /dev/null +++ b/packages/mermaid/scripts/update-release-version.mts @@ -0,0 +1,53 @@ +/* eslint-disable no-console */ + +/** + * @file Update the MERMAID_RELEASE_VERSION placeholder in the documentation source files with the current version of mermaid. + * So contributors adding new features will only have to add the placeholder and not worry about updating the version number. + * + */ +import { posix } from 'path'; +import { + getGlobs, + getFilesFromGlobs, + SOURCE_DOCS_DIR, + readSyncedUTF8file, + MERMAID_RELEASE_VERSION, +} from './docs.mjs'; +import { writeFile } from 'fs/promises'; + +const verifyOnly: boolean = process.argv.includes('--verify'); +const versionPlaceholder = ''; + +const main = async () => { + const sourceDirGlob = posix.join('.', SOURCE_DOCS_DIR, '**'); + const mdFileGlobs = getGlobs([posix.join(sourceDirGlob, '*.md')]); + mdFileGlobs.push('!**/community/development.md'); + const mdFiles = await getFilesFromGlobs(mdFileGlobs); + mdFiles.sort(); + const mdFilesWithPlaceholder: string[] = []; + for (const mdFile of mdFiles) { + const content = readSyncedUTF8file(mdFile); + if (content.includes(versionPlaceholder)) { + mdFilesWithPlaceholder.push(mdFile); + } + } + + if (mdFilesWithPlaceholder.length === 0) { + return; + } + + if (verifyOnly) { + console.log( + `${mdFilesWithPlaceholder.length} file(s) were found with the placeholder ${versionPlaceholder}. Run \`pnpm --filter mermaid docs:release-version\` to update them.` + ); + process.exit(1); + } + + for (const mdFile of mdFilesWithPlaceholder) { + const content = readSyncedUTF8file(mdFile); + const newContent = content.replace(versionPlaceholder, MERMAID_RELEASE_VERSION); + await writeFile(mdFile, newContent); + } +}; + +void main(); diff --git a/packages/mermaid/src/docs/community/development.md b/packages/mermaid/src/docs/community/development.md index a5aa39539..93146f0c3 100644 --- a/packages/mermaid/src/docs/community/development.md +++ b/packages/mermaid/src/docs/community/development.md @@ -212,6 +212,9 @@ If the users have no way to know that things have changed, then you haven't real Likewise, if users don't know that there is a new feature that you've implemented, it will forever remain unknown and unused. The documentation has to be updated to users know that things have changed and added! +If you are adding a new feature, add `(v+)` in the title or description. It will be replaced automatically with the current version number when the release happens. + +eg: `# Feature Name (v+)` We know it can sometimes be hard to code _and_ write user documentation.