From f299f6aff6a78e5e33723be71f840faac23937e9 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 13 Jul 2023 17:08:31 -0400 Subject: [PATCH 1/3] [editorial] markdownlint in less then 1.5 sec --- .github/workflows/checks.yml | 2 +- CONTRIBUTING.md | 2 ++ docs/general/general-attributes.md | 2 -- docs/general/trace-general.md | 2 ++ docs/rpc/rpc-metrics.md | 2 -- docs/rpc/rpc-spans.md | 1 - gulpfile.js | 45 ++++++++++++++++++++++++++++++ package.json | 10 ++++++- 8 files changed, 59 insertions(+), 7 deletions(-) create mode 100644 gulpfile.js diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index 9c94e529c7..4ae744dcbe 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -20,7 +20,7 @@ jobs: run: make check-file-and-folder-names-in-docs - name: run markdownlint - run: make markdownlint + run: npx gulp lint-md yamllint: runs-on: ubuntu-latest diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e69ec11749..158f74ee17 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -137,3 +137,5 @@ make misspell-correction - Add `## v{version} ({date})` under `## Unreleased` - Send staging tag as PR for review. - Create a tag `v{version}` on the merged PR and push remote. + +[nvm]: https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating diff --git a/docs/general/general-attributes.md b/docs/general/general-attributes.md index aba52deb49..a8f0b0e79e 100644 --- a/docs/general/general-attributes.md +++ b/docs/general/general-attributes.md @@ -326,8 +326,6 @@ Examples of where the `enduser.id` value is extracted from: | [JavaEE/JakartaEE Servlet] | `javax.servlet.http.HttpServletRequest.getUserPrincipal()` | | [Windows Communication Foundation] | `ServiceSecurityContext.Current.PrimaryIdentity` | -[Authorization]: https://tools.ietf.org/html/rfc7235#section-4.2 -[OAuth 2.0 Access Token]: https://tools.ietf.org/html/rfc6749#section-3.3 [SAML 2.0 Assertion]: http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html [HTTP Basic/Digest Authentication]: https://tools.ietf.org/html/rfc2617 [OAuth 2.0 Bearer Token]: https://tools.ietf.org/html/rfc6750 diff --git a/docs/general/trace-general.md b/docs/general/trace-general.md index f19b985c3d..c2294a5978 100644 --- a/docs/general/trace-general.md +++ b/docs/general/trace-general.md @@ -35,3 +35,5 @@ The following semantic conventions for spans are defined: Apart from semantic conventions for traces, [metrics](metrics-general.md), [logs](logs-general.md), and [events](events-general.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index f077245b6c..829faf58da 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -131,8 +131,6 @@ To avoid high cardinality, implementations should prefer the most stable of `ser For client-side metrics `server.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to). For server-side spans `server.port` is optional (it describes the port the client is connecting from). -[network.transport]: /docs/general/general-attributes.md#network-attributes - ### Service name On the server process receiving and handling the remote procedure call, the service name provided in `rpc.service` does not necessarily have to match the [`service.name`][] resource attribute. diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 9d600b1d58..aae3c5a0d7 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -131,7 +131,6 @@ This process could expose two RPC endpoints, one called `CurrencyQuotes` (= `rpc In this example, spans representing client request should have their `peer.service` attribute set to `QuoteService` as well to match the server's `service.name` resource attribute. Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service name. -[network attributes]: /docs/general/general-attributes.md#server-and-client-attributes [`service.name`]: /docs/resource/README.md#service [`peer.service`]: /docs/general/general-attributes.md#general-remote-service-attributes diff --git a/gulpfile.js b/gulpfile.js new file mode 100644 index 0000000000..8f0954b12f --- /dev/null +++ b/gulpfile.js @@ -0,0 +1,45 @@ +const gulp = require("gulp"); +const through2 = require("through2"); +const markdownlint = require("markdownlint"); +const yaml = require("js-yaml"); +const fs = require("fs"); + +const markdownFiles = ["**/*.md", "!**/node_modules/**", "!**/.github/**"]; +const config = yaml.load(fs.readFileSync("./.markdownlint.yaml", "utf8")); + +let fileCounter = 0; + +function markdownLintFile(file, encoding, callback) { + const options = { + files: [file.path], + config: config, + }; + + markdownlint(options, function (err, result) { + const _resultString = (result || "").toString(); + // Result is of the form: + // ":\s*: { + console.log(`Processed ${fileCounter} file${fileCounter == 1 ? '' : 's'}.`); + }) + ); +} + +gulp.task("lint-md", lintMarkdown); diff --git a/package.json b/package.json index 2cd780144d..0bbc27cb39 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,15 @@ { "devDependencies": { + "gulp": "^4.0.2", + "js-yaml": "^4.1.0", "markdown-link-check": "3.10.3", "markdown-toc": "^1.2.0", - "markdownlint-cli": "0.31.0" + "markdownlint": "^0.29.0", + "markdownlint-cli": "0.31.0", + "prettier": "^3.0.0", + "through2": "^4.0.2" + }, + "prettier": { + "proseWrap": "preserve" } } From bb363da74c3aa26fe33968affa50da4456926ee1 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 14 Jul 2023 06:59:19 -0400 Subject: [PATCH 2/3] Update make target markdownlint to invoke lint-md task --- Makefile | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Makefile b/Makefile index 1375040f7a..f62f8411f6 100644 --- a/Makefile +++ b/Makefile @@ -65,6 +65,11 @@ markdown-toc: .PHONY: markdownlint markdownlint: + @if ! npm ls markdownlint; then npm install; fi + @npx gulp lint-md + +.PHONY: markdownlint-old +markdownlint-old: @if ! npm ls markdownlint; then npm install; fi @for f in $(ALL_DOCS); do \ echo $$f; \ From 678a7193cd2eecb16c35c10153137f35b45334fb Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 14 Jul 2023 07:08:56 -0400 Subject: [PATCH 3/3] Improved gulp task --- gulpfile.js | 57 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 36 insertions(+), 21 deletions(-) diff --git a/gulpfile.js b/gulpfile.js index 8f0954b12f..a42fd496e5 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -4,42 +4,57 @@ const markdownlint = require("markdownlint"); const yaml = require("js-yaml"); const fs = require("fs"); -const markdownFiles = ["**/*.md", "!**/node_modules/**", "!**/.github/**"]; -const config = yaml.load(fs.readFileSync("./.markdownlint.yaml", "utf8")); - -let fileCounter = 0; +let fileCount = 0, + issueCount = 0; function markdownLintFile(file, encoding, callback) { + const config = yaml.load(fs.readFileSync("./.markdownlint.yaml", "utf8")); const options = { files: [file.path], config: config, }; markdownlint(options, function (err, result) { + if (err) { + console.error("ERROR occurred while running markdownlint: ", err); + return callback(err); + } + const _resultString = (result || "").toString(); - // Result is of the form: - // ":\s*: :\s*: + // + // Strip out any whitespace between the filepath and line number // so that tools can jump directly to the line. - const resultString = _resultString.replace( - /([^:]+):\s*(\d+):(.*)/, - "$1:$2:$3", - ); - if (resultString) console.log(resultString); - fileCounter++; + const resultString = _resultString + .split("\n") + .map((line) => line.replace(/^([^:]+):\s*(\d+):(.*)/, "$1:$2:$3")) + .join("\n"); + if (resultString) { + console.log(resultString); + issueCount++; + } + fileCount++; callback(null, file); }); } function lintMarkdown() { - return ( - gulp - .src(markdownFiles) - .pipe(through2.obj(markdownLintFile)) - .on("end", () => { - console.log(`Processed ${fileCounter} file${fileCounter == 1 ? '' : 's'}.`); - }) - ); + const markdownFiles = ["**/*.md", "!**/node_modules/**", "!**/.github/**"]; + + return gulp + .src(markdownFiles) + .pipe(through2.obj(markdownLintFile)) + .on("end", () => { + console.log( + `Processed ${fileCount} file${ + fileCount == 1 ? "" : "s" + }, ${issueCount} had issues.`, + ); + }); } +lintMarkdown.description = `Run markdownlint on all '*.md' files.`; + gulp.task("lint-md", lintMarkdown);