chore: add markdown link & lint ci (#1684)

* feat: add markdwon link lint ci

* update word

.github/workflows/ci-markdown-link.yml

@@ -0,0 +1,17 @@
+name: Markdown Link Check
+
+on:
+  pull_request:
+
+jobs:
+  markdown-link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: "Markdown Link Check"
+        uses: gaurav-nelson/github-action-markdown-link-check@v1
+        with:
+          config-file: '.markdown-link-check.json'
+          use-quiet-mode: 'yes'
+          use-verbose-mode: 'yes'

.github/workflows/ci-markdownlint.yml

@@ -0,0 +1,20 @@
+name: Markdown Lint Check
+
+on:
+  pull_request:
+
+jobs:
+  markdownlint-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # equivalent cli: markdownlint-cli2  "**/*.md" "#**/CHANGELOG.md"  --config .markdownlint.json
+      - name: "Markdown Lint Check"
+        uses: DavidAnson/markdownlint-cli2-action@v16
+        with:
+          fix: false
+          globs: |
+            **/*.md
+            !**/CHANGELOG.md
+          continue-on-error: true

.markdown-link-check.json

@@ -0,0 +1,10 @@
+{
+  "ignorePatterns": [
+    {
+      "pattern": "^http://localhost"
+    }
+  ],
+  "timeout": "5s",
+  "retryOn429": true,
+  "aliveStatusCodes": [200, 206, 429]
+}

.markdownlint.json

@@ -0,0 +1,13 @@
+{
+  "emphasis-style": false,
+  "line-length": false,
+  "link-fragments": false,
+  "list-marker-space": false,
+  "no-emphasis-as-heading": false,
+  "no-hard-tabs": false,
+  "no-inline-html": false,
+  "no-trailing-punctuation": false,
+  "no-trailing-spaces": true,
+  "custom-rules-below-this-point": false,
+  "trim-code-block-and-unindent": true
+}

CONTRIBUTING.md

@@ -24,7 +24,7 @@ conforms to the specification, but the interface and structure are flexible.
 It is preferable to have contributions follow the idioms of the language
 rather than conform to specific API names or argument patterns in the spec.
 
-For a deeper discussion, see: https://github.com/open-telemetry/opentelemetry-specification/issues/165
+For a deeper discussion, see: <https://github.com/open-telemetry/opentelemetry-specification/issues/165>
 
 ## Getting started
 
@@ -40,6 +40,7 @@ git clone [email protected]:YOUR_GITHUB_NAME/opentelemetry-ruby.git
 ```
 
 or
+
 ```sh
 git clone https://github.com/YOUR_GITHUB_NAME/opentelemetry-ruby.git
 ```
@@ -66,11 +67,11 @@ _Setting up a running Ruby environment is outside the scope of this document._
 
 This repository contains multiple Ruby gems:
 
- *  `opentelemetry-api` located in the `api` directory
- *  `opentelemetry-sdk` located in the `sdk` directory
- *  Various instrumentation gems located in subdirectories of `instrumentation`
- *  Various exporter gems located in subdirectories of `exporter`
- *  `opentelemetry-resource_detectors` located in the `resource_detectors` directory
+*  `opentelemetry-api` located in the `api` directory
+*  `opentelemetry-sdk` located in the `sdk` directory
+*  Various instrumentation gems located in subdirectories of `instrumentation`
+*  Various exporter gems located in subdirectories of `exporter`
+*  `opentelemetry-resource_detectors` located in the `resource_detectors` directory
 
 Each of these gems has its configuration and tests.
 
@@ -89,10 +90,10 @@ configuration details.
 
 The services provided include:
 
- *  `app` - main container environment scoped to the `/app` directory. Used
+*  `app` - main container environment scoped to the `/app` directory. Used
     primarily to build and tag the `opentelemetry/opentelemetry-ruby:latest` image.
- *  `api` - convenience environment scoped to the `api` gem in the `/app/api` directory.
- *  `sdk` - convenience environment scoped to the `sdk` gem in the `/app/sdk` directory.
+*  `api` - convenience environment scoped to the `api` gem in the `/app/api` directory.
+*  `sdk` - convenience environment scoped to the `sdk` gem in the `/app/sdk` directory.
 
 To test using Docker:
 
@@ -154,8 +155,8 @@ to ensure that your code complies before opening a pull request.
 We also use Yard to generate class documentation automatically. Among other
 things, this means:
 
- *  Methods and arguments should include the appropriate type annotations
- *  You can use markdown formatting in your documentation comments
+*  Methods and arguments should include the appropriate type annotations
+*  You can use markdown formatting in your documentation comments
 
 You can generate the docs locally to see the results, by running:
 
@@ -249,7 +250,7 @@ Releases are normally performed using GitHub Actions.
      *  For each gem, it will create a release tag and a GitHub release.
      *  It will build and push the gems to rubygems.
      *  It will build the docs and push them to
-        https://open-telemetry.github.io/opentelemetry-ruby
+        <https://open-telemetry.github.io/opentelemetry-ruby>
      *  If the releases succeed, the script will update the release pull
         request with the results and change its label to `release: complete`.
         If something went wrong, the script will, if possible, report the error
@@ -269,15 +270,15 @@ review the release logs for the GitHub Actions workflows.
 
 There are four GitHub actions workflows related to releases.
 
- *  `Open release request` is the main release entrypoint, and is used to open
+*  `Open release request` is the main release entrypoint, and is used to open
     a release pull request. If something goes wrong with this process, the logs
     will appear in the workflow run.
- *  `Force release` is generally used only to restart a failed release.
- *  `[release hook] Update open releases` is run on pushes to the main branch,
+*  `Force release` is generally used only to restart a failed release.
+*  `[release hook] Update open releases` is run on pushes to the main branch,
     and pushes warnings to open release pull requests if you make modifications
     before triggering the release (i.e. because you might need to update the
     changelogs.)
- *  `[release hook] Process release` is the main release automation script and
+*  `[release hook] Process release` is the main release automation script and
     is run when a pull request is closed. If it determines that a release pull
     request was merged, it kicks off the release process for the affected gems.
     It also updates the label on a closed release pull request. Finally, it
@@ -320,7 +321,7 @@ changed gems.
 
 To force-release, assuming the version and changelog are already modified:
 
-```
+```sh
 toys release perform --rubygems-api-key=$API_KEY $GEM_NAME $GEM_VERSION
 ```
 
@@ -338,17 +339,17 @@ not correspond exactly to the gem name.
 
 For releases to succeed, new gems MUST include the following:
 
- *  The above configuration entry.
- *  The `*.gemspec` file, with the name matching the gem name.
- *  A `version.rb` file in the standard location, or in a location listed in
+*  The above configuration entry.
+*  The `*.gemspec` file, with the name matching the gem name.
+*  A `version.rb` file in the standard location, or in a location listed in
     the configuration.
- *  A `CHANGELOG.md` file.
- *  A `yard` rake task.
+*  A `CHANGELOG.md` file.
+*  A `yard` rake task.
 
 [cncf-cla]: https://identity.linuxfoundation.org/projects/cncf
 [github-draft]: https://github.blog/2019-02-14-introducing-draft-pull-requests/
 [kube-github-workflow-pr]: https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md#7-create-a-pull-request
-[otel-contributor-guide]: https://github.com/open-telemetry/community/blob/master/CONTRIBUTING.md
-[otel-github-workflow]: https://github.com/open-telemetry/community/blob/master/CONTRIBUTING.md#github-workflow
+[otel-contributor-guide]: https://github.com/open-telemetry/community/blob/main/guides/contributor/README.md
+[otel-github-workflow]: https://github.com/open-telemetry/community/blob/main/guides/contributor/processes.md#workflows
 [otel-lib-guidelines]: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/library-guidelines.md
 [otel-specification]: https://github.com/open-telemetry/opentelemetry-specification

README.md

@@ -63,6 +63,7 @@ the [Ruby language](https://www.ruby-lang.org/en/downloads/branches/).
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
 - For help or feedback on this project, join us in [GitHub Discussions][discussions-url].
+- For more examples, check [SDK example][examples-github].
 
 ## License
 

api/README.md

@@ -21,7 +21,7 @@ data should depend only on `opentelemetry-api`, deferring the choice of concrete
 
 Install the gem using:
 
-```
+```sh
 gem install opentelemetry-api
 ```
 
@@ -58,7 +58,6 @@ The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special int
 
 The `opentelemetry-api` gem is distributed under the Apache 2.0 license. See [LICENSE][license-github] for more information.
 
-
 [opentelemetry-home]: https://opentelemetry.io
 [bundler-home]: https://bundler.io
 [repo-github]: https://github.com/open-telemetry/opentelemetry-ruby

common/README.md

@@ -16,7 +16,7 @@ The `opentelemetry-common` gem provides common helpers for semantic conventions,
 
 Install the gem using:
 
-```
+```sh
 gem install opentelemetry-common
 ```
 

examples/http/README.md

@@ -11,19 +11,21 @@ This is a simple example that demonstrates tracing an HTTP request from client t
 ### Running the example
 
 Install gems
+
 ```sh
 bundle install
 ```
 
 Start the server
+
 ```sh
 ruby server.rb
 ```
 
 In a separate terminal window, run the client to make a single request:
+
 ```sh
 ruby client.rb
 ```
 
 You should see console exporter output for both the client and server sessions.
-

examples/metrics_sdk/README.md

@@ -1,22 +1,22 @@
 # OpenTelemetry Ruby Metrics SDK Example
 
-### metrics_collect.rb
+## metrics_collect.rb
 
 Run the script to see the metric data from console
 
 ```sh
 ruby metrics_collect.rb
 ```
 
-### metrics_collect_otlp.rb
+## metrics_collect_otlp.rb
 
 **WARN: this example doesn't work on alpine aarch64 container due to grpc installation issues.**
 
 This example tests both the metrics sdk and the metrics otlp http exporter.
 
 You can view the metrics in your favored backend (e.g. jaeger).
 
-#### 1. Set up the local opentelemetry-collector.
+### 1. Set up the local opentelemetry-collector.
 
 Given you have a `config.yml` file in your current directory and Docker is installed on your machine, run the following commands to pull the collector image and run the collector.
 
@@ -56,17 +56,17 @@ service:
 
 More information on how to setup the OTel collector can be found in the in [quick start docs](https://opentelemetry.io/docs/collector/quick-start/).
 
-#### 2. Assign the endpoint value to your destination address
+### 2. Assign the endpoint value to your destination address
 
-```
+```sh
 # Using environment variable
 ENV['OTEL_EXPORTER_OTLP_METRICS_ENDPOINT'] = 'http://host.docker.internal:4318/v1/metrics'
 
 # Or using export command
 export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://host.docker.internal:4318/v1/metrics
 ```
 
-#### 3. Run the script to send metric data to OTLP collector
+### 3. Run the script to send metric data to OTLP collector
 
 ```sh
 ruby metrics_collect_otlp.rb

exporter/jaeger/README.md

@@ -18,7 +18,7 @@ Generally, *libraries* that produce telemetry data should avoid depending direct
 
 Install the gem using:
 
-```
+```sh
 gem install opentelemetry-sdk
 gem install opentelemetry-exporter-jaeger
 ```
@@ -104,7 +104,6 @@ The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special int
 
 The `opentelemetry-exporter-jaeger` gem is distributed under the Apache 2.0 license. See [LICENSE][license-github] for more information.
 
-
 [jaeger-home]: https://www.jaegertracing.io
 [opentelemetry-home]: https://opentelemetry.io
 [bundler-home]: https://bundler.io

exporter/otlp-common/README.md

@@ -26,12 +26,9 @@ The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special int
 
 The `opentelemetry-exporter-otlp-common` gem is distributed under the Apache 2.0 license. See [LICENSE][license-github] for more information.
 
-[opentelemetry-collector-home]: https://opentelemetry.io/docs/collector/about/
 [opentelemetry-home]: https://opentelemetry.io
-[bundler-home]: https://bundler.io
 [repo-github]: https://github.com/open-telemetry/opentelemetry-ruby
 [license-github]: https://github.com/open-telemetry/opentelemetry-ruby/blob/main/LICENSE
-[examples-github]: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/examples
 [ruby-sig]: https://github.com/open-telemetry/community#ruby-sig
 [community-meetings]: https://github.com/open-telemetry/community#community-meetings
 [discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions

exporter/otlp-grpc/README.md

@@ -22,7 +22,7 @@ This gem supports the [v0.11.0 release](https://github.com/open-telemetry/opente
 
 Install the gem using:
 
-```
+```sh
 gem install opentelemetry-sdk
 gem install opentelemetry-exporter-otlp-grpc
 ```
@@ -82,7 +82,6 @@ The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special int
 
 The `opentelemetry-exporter-otlp-grpc` gem is distributed under the Apache 2.0 license. See [LICENSE][license-github] for more information.
 
-
 [opentelemetry-collector-home]: https://opentelemetry.io/docs/collector/about/
 [opentelemetry-home]: https://opentelemetry.io
 [bundler-home]: https://bundler.io

exporter/otlp-http/README.md

@@ -22,7 +22,7 @@ This gem supports the [v0.11.0 release](https://github.com/open-telemetry/opente
 
 Install the gem using:
 
-```
+```sh
 gem install opentelemetry-sdk
 gem install opentelemetry-exporter-otlp-http
 ```
@@ -92,7 +92,6 @@ The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special int
 
 The `opentelemetry-exporter-otlp-http` gem is distributed under the Apache 2.0 license. See [LICENSE][license-github] for more information.
 
-
 [opentelemetry-collector-home]: https://opentelemetry.io/docs/collector/about/
 [opentelemetry-home]: https://opentelemetry.io
 [bundler-home]: https://bundler.io