From 7794d36a372b7cb448f5a637765a8fe2e1431d95 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Thu, 17 Sep 2020 18:53:37 +0200 Subject: [PATCH] tools,doc: enforce alphabetical order for md refs PR-URL: https://github.com/nodejs/node/pull/35244 Reviewed-By: Rich Trott Reviewed-By: Shelley Vohr --- doc/api/inspector.md | 4 ++-- doc/api/punycode.md | 2 +- doc/api/wasi.md | 2 +- doc/guides/backporting-to-release-lines.md | 2 +- doc/guides/collaborator-guide.md | 2 +- doc/guides/contributing/pull-requests.md | 8 ++++---- doc/guides/cpp-style-guide.md | 8 ++++---- doc/guides/maintaining-V8.md | 4 ++-- doc/guides/maintaining-icu.md | 4 ++-- doc/guides/releases.md | 4 ++-- doc/guides/writing-and-running-benchmarks.md | 6 +++--- doc/guides/writing-tests.md | 4 ++-- onboarding.md | 4 ++-- src/README.md | 8 ++++---- test/wpt/README.md | 2 +- tools/doc/checkLinks.js | 21 +++++++++++++++++--- tools/icu/README.md | 2 +- 17 files changed, 51 insertions(+), 36 deletions(-) diff --git a/doc/api/inspector.md b/doc/api/inspector.md index f541b9eb99fb68..7dc359a0185404 100644 --- a/doc/api/inspector.md +++ b/doc/api/inspector.md @@ -239,8 +239,8 @@ session.post('HeapProfiler.takeHeapSnapshot', null, (err, r) => { }); ``` -[`'Debugger.paused'`]: https://chromedevtools.github.io/devtools-protocol/v8/Debugger#event-paused -[`session.connect()`]: #inspector_session_connect [CPU Profiler]: https://chromedevtools.github.io/devtools-protocol/v8/Profiler [Chrome DevTools Protocol Viewer]: https://chromedevtools.github.io/devtools-protocol/v8/ [Heap Profiler]: https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler +[`'Debugger.paused'`]: https://chromedevtools.github.io/devtools-protocol/v8/Debugger#event-paused +[`session.connect()`]: #inspector_session_connect diff --git a/doc/api/punycode.md b/doc/api/punycode.md index d19d79f8195a78..620585afa484c1 100644 --- a/doc/api/punycode.md +++ b/doc/api/punycode.md @@ -148,5 +148,5 @@ added: v0.6.1 Returns a string identifying the current [Punycode.js][] version number. -[Punycode.js]: https://github.com/bestiejs/punycode.js [Punycode]: https://tools.ietf.org/html/rfc3492 +[Punycode.js]: https://github.com/bestiejs/punycode.js diff --git a/doc/api/wasi.md b/doc/api/wasi.md index 85a75bd104f857..66971aa0631540 100644 --- a/doc/api/wasi.md +++ b/doc/api/wasi.md @@ -162,6 +162,6 @@ added: should be passed as the `wasi_snapshot_preview1` import during the instantiation of a [`WebAssembly.Instance`][]. +[WebAssembly System Interface]: https://wasi.dev/ [`WebAssembly.Instance`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance [`WebAssembly.Memory`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory -[WebAssembly System Interface]: https://wasi.dev/ diff --git a/doc/guides/backporting-to-release-lines.md b/doc/guides/backporting-to-release-lines.md index 5a96b160351700..90b4a3dcaf328c 100644 --- a/doc/guides/backporting-to-release-lines.md +++ b/doc/guides/backporting-to-release-lines.md @@ -89,6 +89,6 @@ replace that with the staging branch for the targeted release line. After the pull request lands, replace the `backport-requested-v10.x` label on the original pull request with `backported-to-v10.x`. -[Release Schedule]: https://github.com/nodejs/Release#release-schedule1 [Release Plan]: https://github.com/nodejs/Release#release-plan +[Release Schedule]: https://github.com/nodejs/Release#release-schedule1 [`node-test-pull-request`]: https://ci.nodejs.org/job/node-test-pull-request/build diff --git a/doc/guides/collaborator-guide.md b/doc/guides/collaborator-guide.md index 2867a83df177ce..6f408783449ae0 100644 --- a/doc/guides/collaborator-guide.md +++ b/doc/guides/collaborator-guide.md @@ -771,10 +771,10 @@ If you cannot find who to cc for a file, `git shortlog -n -s ` can help. [backporting guide]: backporting-to-release-lines.md [commit message guidelines]: contributing/pull-requests.md#commit-message-guidelines [commit-example]: https://github.com/nodejs/node/commit/b636ba8186 +[git-email]: https://help.github.com/articles/setting-your-commit-email-address-in-git/ [git-node]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md [git-node-metadata]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md#git-node-metadata [git-username]: https://help.github.com/articles/setting-your-username-in-git/ -[git-email]: https://help.github.com/articles/setting-your-commit-email-address-in-git/ [node-core-utils-credentials]: https://github.com/nodejs/node-core-utils#setting-up-credentials [node-core-utils-issues]: https://github.com/nodejs/node-core-utils/issues [unreliable tests]: https://github.com/nodejs/node/issues?q=is%3Aopen+is%3Aissue+label%3A%22CI+%2F+flaky+test%22 diff --git a/doc/guides/contributing/pull-requests.md b/doc/guides/contributing/pull-requests.md index 18c84068380fa4..5cdf6e82f19ec4 100644 --- a/doc/guides/contributing/pull-requests.md +++ b/doc/guides/contributing/pull-requests.md @@ -593,15 +593,15 @@ widely used, so don't be discouraged! If you want to know more about the code review and the landing process, see the [Collaborator Guide][]. -[approved]: #getting-approvals-for-your-pull-request -[benchmark results]: ../writing-and-running-benchmarks.md [Building guide]: ../../../BUILDING.md [CI (Continuous Integration) test run]: #ci-testing [Code of Conduct]: https://github.com/nodejs/admin/blob/master/CODE_OF_CONDUCT.md [Collaborator Guide]: ../collaborator-guide.md +[IRC in the #node-dev channel]: https://webchat.freenode.net?channels=node-dev&uio=d4 +[Onboarding guide]: ../../../onboarding.md +[approved]: #getting-approvals-for-your-pull-request +[benchmark results]: ../writing-and-running-benchmarks.md [guide for writing tests in Node.js]: ../writing-tests.md [hiding-a-comment]: https://help.github.com/articles/managing-disruptive-comments/#hiding-a-comment [https://ci.nodejs.org/]: https://ci.nodejs.org/ -[IRC in the #node-dev channel]: https://webchat.freenode.net?channels=node-dev&uio=d4 -[Onboarding guide]: ../../../onboarding.md [running tests]: ../../../BUILDING.md#running-tests diff --git a/doc/guides/cpp-style-guide.md b/doc/guides/cpp-style-guide.md index adf8f0481697f8..56f3f5b4c84094 100644 --- a/doc/guides/cpp-style-guide.md +++ b/doc/guides/cpp-style-guide.md @@ -392,15 +392,15 @@ Node.js is built [without C++ exception handling][], so code using `throw` or even `try` and `catch` **will** break. [C++ Core Guidelines]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines -[Google C++ Style Guide]: https://google.github.io/styleguide/cppguide.html -[Google’s `cpplint`]: https://github.com/google/styleguide -[errors]: https://github.com/nodejs/node/blob/master/doc/guides/using-internal-errors.md [ES.47]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-nullptr [ES.48]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-casts [ES.49]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-casts-named +[Google C++ Style Guide]: https://google.github.io/styleguide/cppguide.html +[Google’s `cpplint`]: https://github.com/google/styleguide [R.20]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-owner [R.21]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-unique [Run Time Type Information]: https://en.wikipedia.org/wiki/Run-time_type_information +[aliased_buffer.h]: https://github.com/nodejs/node/blob/master/src/aliased_buffer.h#L12 [cppref_auto_ptr]: https://en.cppreference.com/w/cpp/memory/auto_ptr +[errors]: https://github.com/nodejs/node/blob/master/doc/guides/using-internal-errors.md [without C++ exception handling]: https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_exceptions.html#intro.using.exception.no -[aliased_buffer.h]: https://github.com/nodejs/node/blob/master/src/aliased_buffer.h#L12 diff --git a/doc/guides/maintaining-V8.md b/doc/guides/maintaining-V8.md index f57b6f38840707..291c7eb0d9aadd 100644 --- a/doc/guides/maintaining-V8.md +++ b/doc/guides/maintaining-V8.md @@ -415,8 +415,8 @@ This would require some tooling to: as their support has ended. [ChromiumReleaseCalendar]: https://www.chromium.org/developers/calendar -[Node.js `canary` branch]: https://github.com/nodejs/node-v8/tree/canary [Node.js CI]: https://ci.nodejs.org/job/node-test-pull-request/ +[Node.js `canary` branch]: https://github.com/nodejs/node-v8/tree/canary [NodeJS-Backport-Approved-Chromium]: https://bugs.chromium.org/p/chromium/issues/list?can=1&q=label%3ANodeJS-Backport-Approved [NodeJS-Backport-Approved-V8]: https://bugs.chromium.org/p/v8/issues/list?can=1&q=label%3ANodeJS-Backport-Approved [NodeJS-Backport-Done-Chromium]: https://bugs.chromium.org/p/chromium/issues/list?can=1&q=label%3ANodeJS-Backport-Done @@ -425,10 +425,10 @@ as their support has ended. [NodeJS-Backport-Rejected-V8]: https://bugs.chromium.org/p/v8/issues/list?can=1&q=label%3ANodeJS-Backport-Rejected [NodeJS-Backport-Review-Chromium]: https://bugs.chromium.org/p/chromium/issues/list?can=1&q=label%3ANodeJS-Backport-Review [NodeJS-Backport-Review-V8]: https://bugs.chromium.org/p/v8/issues/list?can=1&q=label%3ANodeJS-Backport-Review -[`git-node`]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md#git-node-v8 [V8 CI]: https://ci.nodejs.org/job/node-test-commit-v8-linux/ [V8ActiveBranches]: https://build.chromium.org/p/client.v8.branches/console [V8Contributing]: https://github.com/v8/v8/wiki/Contributing [V8MergingPatching]: https://github.com/v8/v8/wiki/Merging%20&%20Patching [V8TemplateMergeRequest]: https://bugs.chromium.org/p/v8/issues/entry?template=Node.js%20merge%20request [V8TemplateUpstreamBug]: https://bugs.chromium.org/p/v8/issues/entry?template=Node.js%20upstream%20bug +[`git-node`]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md#git-node-v8 diff --git a/doc/guides/maintaining-icu.md b/doc/guides/maintaining-icu.md index bf5727d4e865c3..f83a435b847c90 100644 --- a/doc/guides/maintaining-icu.md +++ b/doc/guides/maintaining-icu.md @@ -261,8 +261,8 @@ Node.js (see the top level README.md). Only modifying `icu-small` would cause the patch not to be landed in case the user specifies the ICU source code another way. +[CLDR]: https://unicode.org/cldr +[Ecma402]: https://github.com/tc39/ecma402 [ICU]: http://icu-project.org [Unicode]: https://unicode.org [tz]: https://www.iana.org/time-zones -[CLDR]: https://unicode.org/cldr -[Ecma402]: https://github.com/tc39/ecma402 diff --git a/doc/guides/releases.md b/doc/guides/releases.md index e66204e8d007a0..93e5fb85ffa3c1 100644 --- a/doc/guides/releases.md +++ b/doc/guides/releases.md @@ -869,9 +869,9 @@ test, or doc-related are to be listed as notable changes. Some SEMVER-MINOR commits may be listed as notable changes on a case-by-case basis. Use your judgment there. -[CI lockdown procedure]: https://github.com/nodejs/build/blob/master/doc/jenkins-guide.md#restricting-access-for-security-releases [Build issue tracker]: https://github.com/nodejs/build/issues/new +[CI lockdown procedure]: https://github.com/nodejs/build/blob/master/doc/jenkins-guide.md#restricting-access-for-security-releases +[Partner Communities]: https://github.com/nodejs/community-committee/blob/master/governance/PARTNER_COMMUNITIES.md [nodejs.org release-post.js script]: https://github.com/nodejs/nodejs.org/blob/master/scripts/release-post.js [nodejs.org repository]: https://github.com/nodejs/nodejs.org -[Partner Communities]: https://github.com/nodejs/community-committee/blob/master/governance/PARTNER_COMMUNITIES.md [webchat.freenode.net]: https://webchat.freenode.net/ diff --git a/doc/guides/writing-and-running-benchmarks.md b/doc/guides/writing-and-running-benchmarks.md index 5f630ccc1f805d..b6b22d75c17e2c 100644 --- a/doc/guides/writing-and-running-benchmarks.md +++ b/doc/guides/writing-and-running-benchmarks.md @@ -551,8 +551,8 @@ Supported options keys are: benchmarker [autocannon]: https://github.com/mcollina/autocannon -[wrk]: https://github.com/wg/wrk -[t-test]: https://en.wikipedia.org/wiki/Student%27s_t-test#Equal_or_unequal_sample_sizes.2C_unequal_variances +[benchmark-ci]: https://github.com/nodejs/benchmarking/blob/master/docs/core_benchmarks.md [git-for-windows]: https://git-scm.com/download/win [nghttp2.org]: https://nghttp2.org -[benchmark-ci]: https://github.com/nodejs/benchmarking/blob/master/docs/core_benchmarks.md +[t-test]: https://en.wikipedia.org/wiki/Student%27s_t-test#Equal_or_unequal_sample_sizes.2C_unequal_variances +[wrk]: https://github.com/wg/wrk diff --git a/doc/guides/writing-tests.md b/doc/guides/writing-tests.md index 0aa4cb8221f278..b7d92709444678 100644 --- a/doc/guides/writing-tests.md +++ b/doc/guides/writing-tests.md @@ -434,9 +434,9 @@ Nightly coverage reports for the Node.js master branch are available at [ASCII]: https://man7.org/linux/man-pages/man7/ascii.7.html [Google Test]: https://github.com/google/googletest +[Test Coverage section of the Building guide]: https://github.com/nodejs/node/blob/master/BUILDING.md#running-coverage [`common` module]: https://github.com/nodejs/node/blob/master/test/common/README.md [all maintained branches]: https://github.com/nodejs/lts +[directory structure overview]: https://github.com/nodejs/node/blob/master/test/README.md#test-directories [node.green]: https://node.green/ [test fixture]: https://github.com/google/googletest/blob/master/googletest/docs/Primer.md#test-fixtures-using-the-same-data-configuration-for-multiple-tests -[Test Coverage section of the Building guide]: https://github.com/nodejs/node/blob/master/BUILDING.md#running-coverage -[directory structure overview]: https://github.com/nodejs/node/blob/master/test/README.md#test-directories diff --git a/onboarding.md b/onboarding.md index ce176be9a6ab67..8036e459f5122a 100644 --- a/onboarding.md +++ b/onboarding.md @@ -245,12 +245,12 @@ needs to be pointed out separately during the onboarding. the [summit](https://github.com/nodejs/summit) repository for details. [Code of Conduct]: https://github.com/nodejs/admin/blob/master/CODE_OF_CONDUCT.md +[Landing Pull Requests]: doc/guides/collaborator-guide.md#landing-pull-requests +[Publicizing or hiding organization membership]: https://help.github.com/articles/publicizing-or-hiding-organization-membership/ [`author-ready`]: doc/guides/collaborator-guide.md#author-ready-pull-requests [`core-validate-commit`]: https://github.com/nodejs/core-validate-commit [`git-node`]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md [`node-core-utils`]: https://github.com/nodejs/node-core-utils -[Landing Pull Requests]: doc/guides/collaborator-guide.md#landing-pull-requests -[Publicizing or hiding organization membership]: https://help.github.com/articles/publicizing-or-hiding-organization-membership/ [set up the credentials]: https://github.com/nodejs/node-core-utils#setting-up-credentials [two-factor authentication]: https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/ [using a TOTP mobile app]: https://help.github.com/articles/configuring-two-factor-authentication-via-a-totp-mobile-app/ diff --git a/src/README.md b/src/README.md index 3cabf72e11e6af..e81f1e1c70b781 100644 --- a/src/README.md +++ b/src/README.md @@ -929,6 +929,10 @@ static void GetUserInfo(const FunctionCallbackInfo& args) { } ``` +[C++ coding style]: ../doc/guides/cpp-style-guide.md +[Callback scopes]: #callback-scopes +[JavaScript value handles]: #js-handles +[N-API]: https://nodejs.org/api/n-api.html [`BaseObject`]: #baseobject [`Context`]: #context [`Environment`]: #environment @@ -951,10 +955,6 @@ static void GetUserInfo(const FunctionCallbackInfo& args) { [`v8.h` in Node.js master]: https://github.com/nodejs/node/blob/master/deps/v8/include/v8.h [`v8.h` in V8 master]: https://github.com/v8/v8/blob/master/include/v8.h [`vm` module]: https://nodejs.org/api/vm.html -[C++ coding style]: ../doc/guides/cpp-style-guide.md -[Callback scopes]: #callback-scopes -[JavaScript value handles]: #js-handles -[N-API]: https://nodejs.org/api/n-api.html [binding function]: #binding-functions [cleanup hooks]: #cleanup-hooks [event loop]: #event-loop diff --git a/test/wpt/README.md b/test/wpt/README.md index d2a47737b0367b..ec30c2176849a7 100644 --- a/test/wpt/README.md +++ b/test/wpt/README.md @@ -164,5 +164,5 @@ Web API, or certain harness has not been ported in our test runner yet. In that case it needs to be marked with `skip` instead of `fail`. [Web Platform Tests]: https://github.com/web-platform-tests/wpt -[git node wpt]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md#git-node-wpt [`test/fixtures/wpt/README.md`]: ../fixtures/wpt/README.md +[git node wpt]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md#git-node-wpt diff --git a/tools/doc/checkLinks.js b/tools/doc/checkLinks.js index eea9af4cc9cfc9..97210ca03076e4 100644 --- a/tools/doc/checkLinks.js +++ b/tools/doc/checkLinks.js @@ -27,11 +27,12 @@ function findMarkdownFilesRecursively(dirPath) { if ( entry.isDirectory() && entry.name !== 'api' && - entry.name !== 'tmp' && - entry.name !== 'fixtures' && entry.name !== 'changelogs' && entry.name !== 'deps' && - entry.name !== 'node_modules' + entry.name !== 'fixtures' && + entry.name !== 'node_modules' && + entry.name !== 'out' && + entry.name !== 'tmp' ) { findMarkdownFilesRecursively(path); } else if (entry.isFile() && extname(entry.name) === '.md') { @@ -46,6 +47,7 @@ function checkFile(path) { .parse(fs.readFileSync(path)); const base = pathToFileURL(path); + let previousDefinitionLabel; for (const node of getLinksRecursively(tree)) { const targetURL = new URL(node.url, base); if (targetURL.protocol === 'file:' && !fs.existsSync(targetURL)) { @@ -55,5 +57,18 @@ function checkFile(path) { `Broken link at ${path}:${line}:${column} (${node.url})`); process.exitCode = 1; } + if (node.type === 'definition') { + if (previousDefinitionLabel && + previousDefinitionLabel > node.label) { + const { line, column } = node.position.start; + console.error((process.env.GITHUB_ACTIONS ? + `::error file=${path},line=${line},col=${column}::` : '') + + `Unordered reference at ${path}:${line}:${column} (` + + `"${node.label}" should be before "${previousDefinitionLabel})"` + ); + process.exitCode = 1; + } + previousDefinitionLabel = node.label; + } } } diff --git a/tools/icu/README.md b/tools/icu/README.md index e59f28b71801b7..ab90b760b8c844 100644 --- a/tools/icu/README.md +++ b/tools/icu/README.md @@ -33,5 +33,5 @@ information on maintaining ICU in Node.js internationalization-related APIs in Node.js * [The ICU Homepage][ICU] -[ICU data slicer]: https://github.com/unicode-org/icu/blob/master/docs/userguide/icu_data/buildtool.md [ICU]: http://icu-project.org +[ICU data slicer]: https://github.com/unicode-org/icu/blob/master/docs/userguide/icu_data/buildtool.md