ci: add markdown lint and fixed markdown files (open-telemetry#716)

Co-authored-by: Valentin Marchaud <[email protected]>

Author: Yosef Arbiv

.github/workflows/lint.yml

@@ -13,6 +13,12 @@ jobs:
     steps:
       - uses: actions/checkout@v2
 
+      - name: Lint markdown files
+        uses: avto-dev/markdown-lint@v1
+        with:
+          ignore: "./**/CHANGELOG.md"
+          args: "./**/*.md"
+
       - name: restore lerna
         uses: actions/cache@master # must use unreleased master to cache multiple paths
         id: cache

.markdownlint.json

@@ -0,0 +1,7 @@
+{
+    "MD013": false,
+    "MD024": false,
+    "MD033": false,
+    "MD041": false
+  }
+  

CONTRIBUTING.md

@@ -25,25 +25,29 @@ The Conventional Commits specification is a lightweight convention on top of com
 We use [commitlint](https://github.com/conventional-changelog/commitlint) and [husky](https://github.com/typicode/husky) to prevent bad commit message.
 For example, you want to submit the following commit message `git commit -s -am "my bad commit"`.
 You will receive the following error :
-```
+
+```text
 ✖   type must be one of [ci, feat, fix, docs, style, refactor, perf, test, revert, chore] [type-enum]
 ```
+
 Here an exemple that will pass the verification: `git commit -s -am "chore(opentelemetry-core): update deps"`
 
 ### Fork
 
 In the interest of keeping this repository clean and manageable, you should work from a fork. To create a fork, click the 'Fork' button at the top of the repository, then clone the fork locally using `git clone [email protected]:USERNAME/opentelemetry-js-contrib.git`.
 
 You should also add this repository as an "upstream" repo to your local copy, in order to keep it up to date. You can add this as a remote like so:
-```
+
+```bash
 git remote add upstream https://github.com/open-telemetry/opentelemetry-js-contrib.git
 
 #verify that the upstream exists
 git remote -v
 ```
 
 To update your fork, fetch the upstream repo's branches and commits, then merge your main with upstream's main:
-```
+
+```bash
 git fetch upstream
 git checkout main
 git merge upstream/main
@@ -63,22 +67,26 @@ The `opentelemetry-js-contrib` project is written in TypeScript.
 - `npm test` tests code the same way that our CI will test it.
 - `npm run lint:fix` lint (and maybe fix) any changes.
 
-
 ### Generating API documentation
+
 - `npm run docs` to generate API documentation. Generates the documentation in `packages/opentelemetry-api/docs/out`
 
 ### Generating CHANGELOG documentation
+
 - `npm run changelog` to generate CHANGELOG documentation in your terminal (see [RELEASING.md](RELEASING.md) for more details).
 
 ### Benchmarks
+
 When two or more approaches must be compared, please write a benchmark in the benchmark/index.js module so that we can keep track of the most efficient algorithm.
 
 - `npm run bench` to run your benchmark.
 
 ## Contributing Vendor Components
+
 This repo is generally meant for hosting components that work with popular open-source frameworks and tools. However, it is also possible to contribute components specific to a 3rd party vendor in this repo.
 
 ### Adding a New Vendor Component
+
 Vendor components that are hosted in this repo will be versioned the same as all other contrib components, and released in lockstep with them under the `@opentelemetry` org in NPM.
 
 In exchange, vendor component contributors are expected to:
@@ -96,4 +104,5 @@ In exchange, vendor component contributors are expected to:
 - Update their components' usage of Core APIs upon the introduction of breaking changes upstream
 
 ### Removing Vendor Components
+
 All vendor components are subject to removal from the repo at the sole discretion of the maintainers. Reasons for removal include but are not limited to failing to adhere to any of the expectations defined above in a timely manner. "Timely manner" can vary depending on the urgency of the task, for example if a flaky unit test is blocking a release for the entire repo that would be far more urgent than responding to a question about usage. As a rule of thumb, 2-3 business days is a good goal for non-urgent response times.

README.md

@@ -114,11 +114,13 @@ Node.JS `v8`     | See [Node Support](#node-support) below
 Web Browsers     | ✅ See [Browser Support](#browser-support) below
 
 ### Node Support
+
 Automated tests are run using the latest release of each currently active version of Node.JS.
 While Node.JS v8 is no longer supported by the Node.JS team, the latest version of Node.JS v8 is still included in our testing suite.
 Please note that versions of Node.JS v8 prior to `v8.5.0` will NOT work, because OpenTelemetry Node depends on the `perf_hooks` module introduced in `v8.5.0`
 
 ### Browser Support
+
 Automated browser tests are run in the latest version of Headless Chrome.
 There is currently no list of officially supported browsers, but OpenTelemetry is developed using standard web technologies with wide support and should work in currently supported versions of major browsers.
 

RELEASING.md

@@ -3,7 +3,7 @@
 This repository uses [Release Please](https://github.com/googleapis/release-please) to manage its releases automatically and independently.
 Modified packages are automatically published to NPM when the auto-generated Release Please PR is merged.
 
-# Manual Publishing Process
+## Manual Publishing Process
 
 For posterity, or in the event of any failures with release-please, the process for performing a manual release is below.
 
@@ -42,13 +42,16 @@ Decide on the next `major.minor.patch` release number based on [semver](http://s
 Since we use `lerna`, we can use [lerna-changelog](https://github.com/lerna/lerna-changelog#lerna-changelog)
 
 #### How to use
+
 Pass your [github token](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) to generate the changelog automatically.
 For security reasons, when you create a Github token, select the permissions: under **repo**, select **Access public repositories**, **commit status**.
 
 In your terminal, execute the following command:
+
 ```bash
 GITHUB_AUTH=<your token> lerna-changelog
 ```
+
 It will print something like:
 
 ```md
@@ -64,10 +67,12 @@ It will print something like:
 - Helpful Hacker ([@helpful-hacker](https://github.com/helpful-hacker))
 - [@careful-coder](https://github.com/careful-coder)
 ```
+
 By default lerna-changelog will show all pull requests that have been merged since the latest tagged commit in the repository. That is however only true for pull requests **with certain labels applied** (see [lerna.json](lerna.json) for authorized labels).
 
 You can also use the `--from` and `--to` options to view a different range of pull requests:
-```
+
+```text
 GITHUB_AUTH=xxxxx lerna-changelog --from=v1.0.0 --to=v2.0.0
 ```
 
@@ -102,6 +107,7 @@ done
 Check your e-mail and make sure the number of “you’ve published this module” emails matches the number you expect.
 
 ## Publish the GitHub Release
+
 Publish the GitHub release, ensuring that the tag points to the newly landed commit corresponding to release proposal `x.y.z`.
 
 ## Update CHANGELOG
@@ -110,7 +116,6 @@ Publish the GitHub release, ensuring that the tag points to the newly landed com
 * Create a new commit with the exact title: `Post Release: update CHANGELOG.md`.
 * Go through PR review and merge it to GitHub main branch.
 
-
 ## Known Issues
 
 * The `examples/` and `getting-started/` folders are not part of lerna packages, we need to manually bump the version in `package.json`.

examples/connect/README.md

@@ -3,6 +3,7 @@
 OpenTelemetry Connect Instrumentation allows the user to automatically collect trace data and export them to the backend of choice (Collector Exporter), to give observability to distributed systems.
 
 This is a simple example that demonstrates tracing calls made to Connect API. The example shows key aspects of tracing such as
+
 - Root Span (on Client)
 - Child Span (on Client)
 - Span Events
@@ -11,15 +12,15 @@ This is a simple example that demonstrates tracing calls made to Connect API. Th
 ## Installation
 
 ```sh
-$ # from this directory
-$ npm install
+# from this directory
+npm install
 ```
 
 ## Run the Application
 
 ### Collector - docker container
 
- - Run docker container with collector
+- Run docker container with collector
 
    ```sh
    # from this directory
@@ -28,26 +29,28 @@ $ npm install
 
 ### Server
 
- - Run the server
+- Run the server
 
    ```sh
    # from this directory
    $ npm run server
    ```
 
- - Run the client
+- Run the client
 
    ```sh
    # from this directory
    npm run client
    ```
 
 #### Zipkin UI
-Go to Zipkin with your browser [http://localhost:9411/]()
+
+Go to Zipkin with your browser <http://localhost:9411/>
 
 <p align="center"><img src="images/trace1.png?raw=true"/></p>
 
 ## Useful links
+
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
 - For more information on OpenTelemetry for Node.js, visit: <https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-node>
 

examples/dns/README.md

@@ -12,8 +12,8 @@ shows key aspects of tracing such as
 ## Installation
 
 ```sh
-$ # from this directory
-$ npm install
+# from this directory
+npm install
 ```
 
 Setup [Zipkin Tracing](https://zipkin.io/pages/quickstart.html)
@@ -27,14 +27,14 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/
 - Run the client
 
 ```sh
-$ # from this directory
-$ npm run zipkin:client
+# from this directory
+npm run zipkin:client
 ```
 
 #### Zipkin UI
 
 `zipkin:client` 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)
+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>
 
@@ -43,14 +43,14 @@ Go to Zipkin with your browser [http://localhost:9411/zipkin/traces/(your-trace-
 - Run the client
 
 ```sh
-  $ # from this directory
-  $ npm run jaeger:client
+  # from this directory
+  npm run jaeger:client
 ```
 
 #### Jaeger UI
 
 `jaeger:client` 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)
+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>
 

examples/express/README.md

@@ -4,6 +4,7 @@ OpenTelemetry Express Instrumentation allows the user to automatically collect t
 
 This is a simple example that demonstrates tracing calls made to Express API. The example
 shows key aspects of tracing such as
+
 - Root Span (on Client)
 - Child Span (on Client)
 - Span Events
@@ -12,8 +13,8 @@ shows key aspects of tracing such as
 ## Installation
 
 ```sh
-$ # from this directory
-$ npm install
+# from this directory
+npm install
 ```
 
 Setup [Zipkin Tracing](https://zipkin.io/pages/quickstart.html)
@@ -24,36 +25,37 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/
 
 ### Zipkin
 
- - Run the server
+- Run the server
 
    ```sh
    # from this directory
    $ npm run zipkin:server
    ```
 
- - Run the client
+- Run the client
 
    ```sh
    # from this directory
    npm run zipkin:client
    ```
 
 #### Zipkin UI
+
 `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)
+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.jpg?raw=true"/></p>
 
 ### Jaeger
 
- - Run the server
+- Run the server
 
    ```sh
    # from this directory
    $ npm run jaeger:server
    ```
 
- - Run the client
+- Run the client
 
    ```sh
    # from this directory
@@ -63,11 +65,12 @@ Go to Zipkin with your browser [http://localhost:9411/zipkin/traces/(your-trace-
 #### Jaeger UI
 
 `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)
+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.jpg?raw=true"/></p>
 
 ## Useful links
+
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
 - For more information on OpenTelemetry for Node.js, visit: <https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-node>
 

examples/fastify/README.md

@@ -3,6 +3,7 @@
 OpenTelemetry Fastify Instrumentation allows the user to automatically collect trace data and export them to the backend of choice (Collector Exporter), to give observability to distributed systems.
 
 This is a simple example that demonstrates tracing calls made to Fastify API. The example shows key aspects of tracing such as
+
 - Root Span (on Client)
 - Child Span (on Client)
 - Span Events
@@ -11,15 +12,15 @@ This is a simple example that demonstrates tracing calls made to Fastify API. Th
 ## Installation
 
 ```sh
-$ # from this directory
-$ npm install
+# from this directory
+npm install
 ```
 
 ## Run the Application
 
 ### Collector - docker container
 
- - Run docker container with collector
+- Run docker container with collector
 
    ```sh
    # from this directory
@@ -28,26 +29,28 @@ $ npm install
 
 ### Server
 
- - Run the server
+- Run the server
 
    ```sh
    # from this directory
    $ npm run server
    ```
 
- - Run the client
+- Run the client
 
    ```sh
    # from this directory
    npm run client
    ```
 
 #### Zipkin UI
-Go to Zipkin with your browser [http://localhost:9411/]()
+
+Go to Zipkin with your browser <http://localhost:9411/>
 
 <p align="center"><img src="images/trace1.png?raw=true"/></p>
 
 ## Useful links
+
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
 - For more information on OpenTelemetry for Node.js, visit: <https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-node>