diff --git a/README.md b/README.md index 54fc3c7d..5a54b5d3 100644 --- a/README.md +++ b/README.md @@ -20,12 +20,34 @@ npm test ### Adding the language to the documentation style guide -1. PR the [nodejs/node](https://github.com/nodejs/node) repo adding the language/grammar to the [documentation style guide](https://github.com/nodejs/node/blob/master/doc/guides/doc-style-guide.md) +1. PR the [nodejs/node](https://github.com/nodejs/node) repo adding the + language/grammar to the + [documentation style guide](https://github.com/nodejs/node/blob/master/doc/guides/doc-style-guide.md). ### Adding the language to the linter -1. PR this repo adding the language/grammar -1. Bump this package version, publish it -1. In [node-lint-md-cli-rollup](https://github.com/nodejs/node/tree/master/tools/node-lint-md-cli-rollup), bump the `remark-preset-lint-node` dependency -1. In the `nodejs/node` repo, rebuild the Markdown linter (`make lint-md-rollup`) -1. PR the `nodejs/node` repo with the updated linter +1. PR this repo adding the language/grammar. +1. Bump this package version, publish it. +1. In + [node-lint-md-cli-rollup](https://github.com/nodejs/node/tree/master/tools/node-lint-md-cli-rollup), + bump the `remark-preset-lint-node` dependency. +1. In the `nodejs/node` repo, rebuild the Markdown linter + (`make lint-md-rollup`). +1. PR the `nodejs/node` repo with the updated linter. + +## Environment variables + +#### `NODE_RELEASED_VERSIONS` + +On runtime, the linter will check the environment if the +`NODE_RELEASED_VERSIONS` variable is defined; if it's there, it will use the +content of the variable as a comma-separated list of allowed version numbers. +This list is supposed to be built from the changelog(s), and validates the +version numbers for the `nodejs-yaml-comments` rule. + +For better compatibility with the nodejs/node changelogs, there are a few +exceptions: + +- Version numbers `^0.0.0 || ^0.1.0` are not validated using the provided list, + they are validating using the `vx.x.x` pattern. +- `REPLACEME` placeholder is always valid, regardless it's in the list or not. diff --git a/remark-lint-nodejs-yaml-comments.js b/remark-lint-nodejs-yaml-comments.js index ce27f7e6..b9f5bde8 100644 --- a/remark-lint-nodejs-yaml-comments.js +++ b/remark-lint-nodejs-yaml-comments.js @@ -22,6 +22,17 @@ const validVersionNumberRegex = /^v\d+\.\d+\.\d+$/; const prUrlRegex = new RegExp("^https://github.com/nodejs/node/pull/\\d+$"); const privatePRUrl = "https://github.com/nodejs-private/node-private/pull/"; +let releasedVersions; +let invalidVersionMessage = "version(s) must respect the pattern `vx.x.x` or"; +if (process.env.NODE_RELEASED_VERSIONS) { + console.log("Using release list from env..."); + releasedVersions = process.env.NODE_RELEASED_VERSIONS.split(",").map( + (v) => `v${v}` + ); + invalidVersionMessage = `version not listed in the changelogs, `; +} +invalidVersionMessage += `use the placeholder \`${VERSION_PLACEHOLDER}\``; + const kContainsIllegalKey = Symbol("illegal key"); const kWrongKeyOrder = Symbol("Wrong key order"); function unorderedKeys(meta) { @@ -41,11 +52,16 @@ function containsInvalidVersionNumber(version) { return version.some(containsInvalidVersionNumber); } - return ( - version !== undefined && - version !== VERSION_PLACEHOLDER && - !validVersionNumberRegex.test(version) - ); + if (version === undefined || version === VERSION_PLACEHOLDER) return false; + + if ( + releasedVersions && + // Always ignore 0.0.x and 0.1.x release numbers: + (version[1] !== "0" || (version[3] !== "0" && version[3] !== "1")) + ) + return !releasedVersions.includes(version); + + return !validVersionNumberRegex.test(version); } const getValidSemver = (version) => version === VERSION_PLACEHOLDER ? MAX_SAFE_SEMVER_VERSION : version; @@ -122,11 +138,7 @@ function validateChanges(file, node, changes) { } if (containsInvalidVersionNumber(change.version)) { - file.message( - `changes[${index}]: version(s) must respect the pattern \`vx.x.x\` ` + - `or use the placeholder \`${VERSION_PLACEHOLDER}\``, - node - ); + file.message(`changes[${index}]: ${invalidVersionMessage}`, node); } else if (areVersionsUnordered(change.version)) { file.message(`changes[${index}]: list of versions is not in order`, node); } @@ -180,19 +192,14 @@ function validateMeta(node, file, meta) { } if (containsInvalidVersionNumber(meta.added)) { - file.message( - "Invalid `added` value: version(s) must respect the pattern `vx.x.x` " + - `or use the placeholder \`${VERSION_PLACEHOLDER}\``, - node - ); + file.message(`Invalid \`added\` value: ${invalidVersionMessage}`, node); } else if (areVersionsUnordered(meta.added)) { file.message("Versions in `added` list are not in order", node); } if (containsInvalidVersionNumber(meta.deprecated)) { file.message( - "Invalid `deprecated` value: version(s) must respect the pattern `vx.x.x` " + - `or use the placeholder \`${VERSION_PLACEHOLDER}\``, + `Invalid \`deprecated\` value: ${invalidVersionMessage}`, node ); } else if (areVersionsUnordered(meta.deprecated)) { @@ -200,11 +207,7 @@ function validateMeta(node, file, meta) { } if (containsInvalidVersionNumber(meta.removed)) { - file.message( - "Invalid `removed` value: version(s) must respect the pattern `vx.x.x` " + - `or use the placeholder \`${VERSION_PLACEHOLDER}\``, - node - ); + file.message(`Invalid \`removed\` value: ${invalidVersionMessage}`, node); } else if (areVersionsUnordered(meta.removed)) { file.message("Versions in `removed` list are not in order", node); }