chore(lint): refactor Markdown linting to use markdownlint-cli2 (#4713)

* chore(lint): refactor Markdown linting to use markdownlint-cli2 - first commit is just config changes; lint updates will follow * lint fixes * fix markdownlint for rule MD045/no-alt-text * lint config changes for prefering 'dash' style for rule MD004/ul-style * lint:markdown:fix changes for MD004/ul-style * manually apply this h3->h2 fix that Amir had in his #4703 PR * mention markdown linting in the Linting section of the contributor guide * add link to rules docs --------- Co-authored-by: Marc Pichler <[email protected]>
open-telemetry · May 21, 2024 · e49c4c7 · e49c4c7
1 parent bac68fc
commit e49c4c7
Show file tree

Hide file tree

Showing 40 changed files with 282 additions and 590 deletions.
diff --git a/.github/repository-settings.md b/.github/repository-settings.md
@@ -10,22 +10,22 @@ No changes
 
 ## Collaborators and Teams
 
-* There is currently no `javascript-triagers` role
-* `javascript-maintainers` has `Admin` permission
+- There is currently no `javascript-triagers` role
+- `javascript-maintainers` has `Admin` permission
 
 ## Branches
 
 ## Branch protection rules
 
 ### `main`
 
-* Uncheck "Restrict who can push to matching branches"
-* Check "Require merge queue"
-  * Build concurrency: 5
-  * Minimum pull requests to merge: 1 or after 5 minutes
-  * Maximum pull requests to merge: 5
-  * Check "Only merge non-failing pull requests"
-  * Status check timeout: 60 minutes
+- Uncheck "Restrict who can push to matching branches"
+- Check "Require merge queue"
+  - Build concurrency: 5
+  - Minimum pull requests to merge: 1 or after 5 minutes
+  - Maximum pull requests to merge: 5
+  - Check "Only merge non-failing pull requests"
+  - Status check timeout: 60 minutes
 
 ### `dependabot/**/**`
 
@@ -36,10 +36,10 @@ Our dependencies are managed by a bot which creates PRs from a fork.
 
 This is a special branch which we use to publish the automatically generated docs.
 It is exempt from most protections.
- 
-* "Allow force pushes from everyone" (requires write permission)
+
+- "Allow force pushes from everyone" (requires write permission)
 
 ## Pages
 
-* Source: Deploy from a branch
-* Branch: `gh-pages` `/ (root)`
+- Source: Deploy from a branch
+- Branch: `gh-pages` `/ (root)`
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -21,29 +21,14 @@ jobs:
             package-lock.json
           node-version: '20'
 
-      - name: Lint changelog file
-        uses: avto-dev/markdown-lint@v1
-        with:
-          # Commenting due to
-          # https://github.com/avto-dev/markdown-lint/blob/aab9be9823fcd706f6da3e6ad6c64874c23fbd4c/lint/rules/changelog.js#L51-L71
-          # TODO: adhere to, or overwrite above rule and uncomment rules
-          # rules: "/lint/rules/changelog.js"
-          config: "/lint/config/changelog.yml"
-          args: "./CHANGELOG.md"
-
-      - name: Lint markdown files
-        uses: avto-dev/markdown-lint@v1
-        with:
-          args: "./**/*.md"
-          ignore: './CHANGELOG.md ./experimental/packages/opentelemetry-exporter-metrics-otlp-grpc/protos ./experimental/packages/opentelemetry-exporter-metrics-otlp-proto/protos ./packages/exporter-trace-otlp-grpc/protos ./packages/exporter-trace-otlp-proto/protos'
-
       - name: Bootstrap
         run: npm ci
 
       - name: Lint
         run: |
           npm run lint
           npm run lint:examples
+          npm run lint:markdown
 
       - name: Lint doc files
         run: |

diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
@@ -0,0 +1,15 @@
+// https://github.com/DavidAnson/markdownlint-cli2#markdownlint-cli2jsonc
+{
+  "config": {
+    // https://github.com/DavidAnson/markdownlint/blob/main/README.md#rules--aliases
+    "MD013": false,
+    "MD024": false,
+    "MD033": false,
+    "MD041": false,
+    "MD026": false,
+    "MD004": { "style": "dash" } // ul-style
+  },
+  "gitignore": true,
+  "noBanner": true,
+  "noProgress": true
+}
diff --git a/.markdownlint.json b/.markdownlint.json
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD004 -->
 # CHANGELOG
 
 All notable changes to this project will be documented in this file.
@@ -1917,7 +1918,7 @@ No changes
 * `opentelemetry-api`, `opentelemetry-exporter-prometheus`, `opentelemetry-metrics`
   * [#1137](https://github.com/open-telemetry/opentelemetry-js/pull/1137) Batch observer ([@obecny](https://github.com/obecny))
 * `opentelemetry-exporter-collector`
-  * [#1256](https://github.com/open-telemetry/opentelemetry-js/pull/1256) feat: [Collector Metric Exporter][1/x] Rename CollectorExporter to CollectorTraceExporter  ([@davidwitten](https://github.com/davidwitten))
+  * [#1256](https://github.com/open-telemetry/opentelemetry-js/pull/1256) feat: Collector Metric Exporter [1/x] Rename CollectorExporter to CollectorTraceExporter  ([@davidwitten](https://github.com/davidwitten))
 
 ### :rocket: (Enhancement)
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -247,6 +247,13 @@ cd packages/opentelemetry-module-name
 npm run lint:fix
 ```
 
+Similarly, Markdown files (such as README.md files) can be linted:
+
+```sh
+npm run lint:markdown
+npm run lint:markdown:fix # can automatically fix some Markdown rules
+```
+
 ### Generating docs
 
 We use [typedoc](https://www.npmjs.com/package/typedoc) to generate the api documentation.

diff --git a/README.md b/README.md
@@ -105,7 +105,7 @@ The above example will emit auto-instrumented telemetry about your Node.js appli
 
 ## Library Author
 
-If you are a library author looking to build OpenTelemetry into your library, please see [the documentation][docs]. As a library author, it is important that you only depend on properties and methods published on the public API. If you use any properties or methods from the SDK that are not officially a part of the public API, your library may break if an [Application Owner](#application-owner) uses a different SDK implementation.
+If you are a library author looking to build OpenTelemetry into your library, please see [the documentation][docs]. As a library author, it is important that you only depend on properties and methods published on the public API. If you use any properties or methods from the SDK that are not officially a part of the public API, your library may break if an application owner uses a different SDK implementation.
 
 ## Supported Runtimes
 
@@ -252,7 +252,7 @@ We have a weekly SIG meeting! See the [community page](https://github.com/open-t
 #### Thanks to all the people who already contributed
 
 <a href="https://github.com/open-telemetry/opentelemetry-js/graphs/contributors">
-  <img src="https://contributors-img.web.app/image?repo=open-telemetry/opentelemetry-js" />
+  <img alt="Repo contributors" src="https://contributors-img.web.app/image?repo=open-telemetry/opentelemetry-js" />
 </a>
 
 ## Packages
@@ -349,6 +349,5 @@ Apache 2.0 - See [LICENSE][license-url] for more information.
 [otel-web]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-sdk-trace-web
 [otel-api]: https://github.com/open-telemetry/opentelemetry-js/tree/main/api
 [otel-core]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-core
-[otel-propagator-b3]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-propagator-b3
 
 [spec-versioning]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md
diff --git a/api/CHANGELOG.md b/api/CHANGELOG.md
@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD004 -->
 # CHANGELOG
 
 All notable changes to this project will be documented in this file.

diff --git a/api/README.md b/api/README.md
@@ -112,6 +112,5 @@ Apache 2.0 - See [LICENSE][license-url] for more information.
 
 [discussions-url]: https://github.com/open-telemetry/opentelemetry-js/discussions
 [license-url]: https://github.com/open-telemetry/opentelemetry-js/blob/main/api/LICENSE
-[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
 [docs-tracing]: https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/tracing.md
 [docs-sdk-registration]: https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/sdk-registration.md
diff --git a/doc/contributing/dependencies.md b/doc/contributing/dependencies.md
@@ -25,7 +25,7 @@ An exception is granted for dependencies on `@opentelemetry/api`, which, if used
 
 Packages categorized as third-party and listed under the `"dependencies"` section (e.g., @grpc/grpc-js, @grpc/proto-loader, shimmer, etc.) should remain unpinned and utilize the caret (`^`) symbol. This approach offers several advantages:
 
-* Our users could get bug fixes of those 3rd-party packages easily, without waiting for us to update our library.
-* In cases where multiple packages have dependencies on different versions of the same package, npm will opt for the most recent version, saving space and preventing potential disruptions.
+- Our users could get bug fixes of those 3rd-party packages easily, without waiting for us to update our library.
+- In cases where multiple packages have dependencies on different versions of the same package, npm will opt for the most recent version, saving space and preventing potential disruptions.
 
 It's important to acknowledge that this approach does expose users to potential breaking changes arising from either human error or libraries that do not strictly follow to semver conventions. This trade-off is an inherent aspect of this approach.
diff --git a/doc/sdk-registration.md b/doc/sdk-registration.md
@@ -23,6 +23,7 @@ api.propagation.setGlobalPropagator(httpTraceContextPropagator);
 api.context.setGlobalContextManager(asyncHooksContextManager);
 ```
 
+[opentelemetry-js]: https://github.com/open-telemetry/opentelemetry-js
 [trace-api-docs]: https://open-telemetry.github.io/opentelemetry-js/classes/_opentelemetry_api.TraceAPI.html
 [propagation-api-docs]: https://open-telemetry.github.io/opentelemetry-js/classes/_opentelemetry_api.PropagationAPI.html
 [context-api-docs]: https://open-telemetry.github.io/opentelemetry-js/classes/_opentelemetry_api.ContextAPI.html
diff --git a/doc/upgrade-guide.md b/doc/upgrade-guide.md
@@ -107,7 +107,7 @@ Collector exporter packages and types are renamed:
 
 - All plugins have been removed in favor of instrumentations.
 
-- The `@opentelemetry/propagator-b3` package previously exported three propagators: `B3Propagator`,`B3SinglePropagator`, and `B3MultiPropagator`, but now only exports the `B3Propagator`. It extracts b3 context in single and multi-header encodings, and injects context using the single-header encoding by default, but can be configured to inject context using the multi-header encoding during construction: `new B3Propagator({ injectEncoding: B3InjectEncoding.MULTI_HEADER })`. If you were previously using the `B3SinglePropagator` or `B3MultiPropagator` directly, you should update your code to use the `B3Propagator` with the appropriate configuration. See the [README][otel-propagator-b3] for full details and usage.
+- The `@opentelemetry/propagator-b3` package previously exported three propagators: `B3Propagator`,`B3SinglePropagator`, and `B3MultiPropagator`, but now only exports the `B3Propagator`. It extracts b3 context in single and multi-header encodings, and injects context using the single-header encoding by default, but can be configured to inject context using the multi-header encoding during construction: `new B3Propagator({ injectEncoding: B3InjectEncoding.MULTI_HEADER })`. If you were previously using the `B3SinglePropagator` or `B3MultiPropagator` directly, you should update your code to use the `B3Propagator` with the appropriate configuration. See the [README](https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-propagator-b3/README.md) for full details and usage.
 
 - Sampling configuration via environment variable has changed. If you were using `OTEL_SAMPLING_PROBABILITY` then you should replace it with `OTEL_TRACES_SAMPLER=parentbased_traceidratio` and `OTEL_TRACES_SAMPLER_ARG=<number>` where `<number>` is a number in the [0..1] range, e.g. "0.25". Default is 1.0 if unset.
 

diff --git a/examples/basic-tracer-node/README.md b/examples/basic-tracer-node/README.md
@@ -24,13 +24,13 @@ npm start
 
 Open the Jaeger UI in your browser [http://localhost:16686](http://localhost:16686)
 
-<p align="center"><img src="images/jaeger-ui-list.png?raw=true"/></p>
+<p align="center"><img alt="Jaeger UI showing list of traces" src="images/jaeger-ui-list.png?raw=true"/></p>
 
 Select `basic-service` under *Service Name* and click on *Find Traces*.
 
 Click on the trace to view its details.
 
-<p align="center"><img src="./images/jaeger-ui-detail.png?raw=true"/></p>
+<p align="center"><img alt="Jaeger UI showing a trace" src="./images/jaeger-ui-detail.png?raw=true"/></p>
 
 ## Useful links
 

diff --git a/examples/grpc-js/README.md b/examples/grpc-js/README.md
@@ -36,7 +36,7 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/
 `zipkin:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`).
 Go to Zipkin with your browser <http://localhost:9411/zipkin/traces/(your-trace-id)> (e.g <http://localhost:9411/zipkin/traces/4815c3d576d930189725f1f1d1bdfcc6)>
 
-<p align="center"><img src="./images/zipkin.png"/></p>
+<p align="center"><img alt="Zipkin UI showing a trace" src="./images/zipkin.png"/></p>
 
 ### Jaeger
 
@@ -59,7 +59,7 @@ Go to Zipkin with your browser <http://localhost:9411/zipkin/traces/(your-trace-
 `jaeger:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`).
 Go to Jaeger with your browser <http://localhost:50051/trace/(your-trace-id)> (e.g <http://localhost:50051/trace/4815c3d576d930189725f1f1d1bdfcc6)>
 
-<p align="center"><img src="./images/jaeger.png"/></p>
+<p align="center"><img alt="Jaeger UI showing a trace" src="./images/jaeger.png"/></p>
 
 ## Useful links
 

diff --git a/examples/http/README.md b/examples/http/README.md
@@ -46,7 +46,7 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/
 `zipkin:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`).
 Go to Zipkin with your browser <http://localhost:9411/zipkin/traces/(your-trace-id)> (e.g <http://localhost:9411/zipkin/traces/4815c3d576d930189725f1f1d1bdfcc6>)
 
-<p align="center"><img src="./images/zipkin-ui.png?raw=true"/></p>
+<p align="center"><img alt="Zipkin UI showing a trace" src="./images/zipkin-ui.png?raw=true"/></p>
 
 ### Jaeger
 
@@ -69,7 +69,7 @@ Go to Zipkin with your browser <http://localhost:9411/zipkin/traces/(your-trace-
 `jaeger:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`).
 Go to Jaeger with your browser <http://localhost:16686/trace/(your-trace-id)> (e.g <http://localhost:16686/trace/4815c3d576d930189725f1f1d1bdfcc6>)
 
-<p align="center"><img src="images/jaeger-ui.png?raw=true"/></p>
+<p align="center"><img alt="Jaeger UI showing a trace"  src="images/jaeger-ui.png?raw=true"/></p>
 
 ## Useful links
 

diff --git a/examples/https/README.md b/examples/https/README.md
@@ -56,7 +56,7 @@ npm run docker:start
 Go to Zipkin with your browser <http://localhost:9411/zipkin/traces/(your-trace-id)> (
 e.g <http://localhost:9411/zipkin/traces/4815c3d576d930189725f1f1d1bdfcc6)>
 
-<p align="center"><img src="./images/zipkin-ui.png?raw=true"/></p>
+<p align="center"><img alt="Zipkin UI showing a trace" src="./images/zipkin-ui.png?raw=true"/></p>
 
 ### Jaeger
 
@@ -80,7 +80,7 @@ e.g <http://localhost:9411/zipkin/traces/4815c3d576d930189725f1f1d1bdfcc6)>
 Go to Jaeger with your browser <http://localhost:16686/trace/(your-trace-id)> (
 e.g <http://localhost:16686/trace/4815c3d576d930189725f1f1d1bdfcc6)>
 
-<p align="center"><img src="images/jaeger-ui.png?raw=true"/></p>
+<p align="center"><img alt="Jaeger UI showing a trace" src="images/jaeger-ui.png?raw=true"/></p>
 
 ## Useful links
 

diff --git a/examples/opentracing-shim/README.md b/examples/opentracing-shim/README.md
@@ -45,7 +45,7 @@ $ npm run zipkin:client
 
   Go to Zipkin with your browser <http://localhost:9411/zipkin/traces/(your-trace-id)> (e.g <http://localhost:9411/zipkin/traces/4815c3d576d930189725f1f1d1bdfcc6)>
 
-<p align="center"><img src="./images/zipkin-ui.png?raw=true"/></p>
+<p align="center"><img alt="Zipkin UI showing a trace" src="./images/zipkin-ui.png?raw=true"/></p>
 
 ### Jaeger
 
@@ -71,7 +71,7 @@ $ npm run jaeger:client
 
   Go to Jaeger with your browser <http://localhost:16686/trace/(your-trace-id)> (e.g <http://localhost:16686/trace/4815c3d576d930189725f1f1d1bdfcc6)>
 
-<p align="center"><img src="images/jaeger-ui.png?raw=true"/></p>
+<p align="center"><img alt="Jaeger UI showing a trace" src="images/jaeger-ui.png?raw=true"/></p>
 
 ## Useful links
 

diff --git a/examples/otlp-exporter-node/README.md b/examples/otlp-exporter-node/README.md
@@ -44,8 +44,8 @@ The prometheus client will be available at <http://localhost:9090>.
 
 Note: It may take some time for the application metrics to appear on the Prometheus dashboard.
 
-<p align="center"><img src="../prometheus/images/prom-counter.png?raw=true"/></p>
-<p align="center"><img src="../prometheus/images/prom-updowncounter.png?raw=true"/></p>
+<p align="center"><img alt="Prometheus UI showing a charted Counter" src="../../experimental/examples/prometheus/images/prom-counter.png?raw=true"/></p>
+<p align="center"><img alt="Prometheus UI showing a charted UpDownCounter" src="../../experimental/examples/prometheus/images/prom-updowncounter.png?raw=true"/></p>
 
 ## Useful links
 

diff --git a/experimental/CHANGELOG.md b/experimental/CHANGELOG.md
@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD004 -->
 # CHANGELOG
 
 All notable changes to experimental packages in this project will be documented in this file.

diff --git a/experimental/examples/README.md b/experimental/examples/README.md
@@ -7,7 +7,7 @@ This directory contains examples of how to run real applications with OpenTeleme
 These examples are using work in progress metrics packages.
 
 |Name | Description | Complexity Level |
-------------- | ------------- | ------------ |
+|------------- | ------------- | ------------ |
 |[prometheus](prometheus/) | Basic Metric use with Prometheus (`@opentelemetry/exporter-prometheus`) Exporter | Beginner |
 
 ## Contributing

diff --git a/experimental/examples/opencensus-shim/README.md b/experimental/examples/opencensus-shim/README.md
@@ -64,15 +64,15 @@ Go to Jaeger with your browser <http://localhost:16686/> and click on the "Servi
     - A child for the sleep operation. This was manually instrumented with OpenTelemetry.
       Notice this span is correctly recorded as a child of the OpenCensus instrumentation.
 
-<p align="center"><img src="./images/jaeger-trace.png"/></p>
+<p align="center"><img alt="Jaeger UI showing a trace" src="./images/jaeger-trace.png"/></p>
 
 ## Check the Prometheus metrics
 
 Load the Prometheus metrics endpoint of the server at <http://localhost:9464/metrics> in your
 browser. You should see the `opencensus_io_http_server_*` related metrics in
 the output.
 
-<p align="center"><img src="./images/prom-metrics.png"/></p>
+<p align="center"><img alt="Screenshot showing Prometheus raw metrics" src="./images/prom-metrics.png"/></p>
 
 ## Useful links
 

diff --git a/experimental/examples/prometheus/README.md b/experimental/examples/prometheus/README.md
@@ -58,9 +58,9 @@ prometheus --config.file=prometheus.yml
 
 If you are using the default configurations, the prometheus client will be available at <http://localhost:9090>
 
-<p align="center"><img src="images/prom-counter.png?raw=true"/></p>
-<p align="center"><img src="images/prom-updowncounter.png?raw=true"/></p>
-<p align="center"><img src="images/prom-gauge.png?raw=true"/></p>
+<p align="center"><img alt="Prometheus UI showing a charted Counter" src="images/prom-counter.png?raw=true"/></p>
+<p align="center"><img alt="Prometheus UI showing a charted UpDownCounter" src="images/prom-updowncounter.png?raw=true"/></p>
+<p align="center"><img alt="Prometheus UI showing a charted Gauge" src="images/prom-gauge.png?raw=true"/></p>
 
 ## Useful links
 

diff --git a/experimental/packages/api-events/README.md b/experimental/packages/api-events/README.md
@@ -57,4 +57,4 @@ Apache 2.0 - See [LICENSE][license-url] for more information.
 [license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
 [npm-url]: https://www.npmjs.com/package/@opentelemetry/api-logs
 [npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fapi-logs.svg
-[logs-api-docs]: https://open-telemetry.github.io/opentelemetry-js/modules/_opentelemetry_api_logs.html
+[events-api-docs]: https://open-telemetry.github.io/opentelemetry-js/modules/_opentelemetry_api_events.html
diff --git a/experimental/packages/exporter-logs-otlp-grpc/README.md b/experimental/packages/exporter-logs-otlp-grpc/README.md
@@ -84,7 +84,6 @@ Apache 2.0 - See [LICENSE][license-url] for more information.
 [license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
 [npm-url]: https://www.npmjs.com/package/@opentelemetry/exporter-logs-otlp-grpc
 [npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fexporter-logs-otlp-grpc.svg
-[opentelemetry-collector-url]: https://github.com/open-telemetry/opentelemetry-collector
 [semconv-resource-service-name]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md#service
 [trace-exporter-url]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/exporter-trace-otlp-grpc
 [metrics-exporter-url]: https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-exporter-metrics-otlp-grpc