ci: upgrade GH workflows and fix markdown linting (#958)

.github/workflows/lint.yml

@@ -1,15 +1,16 @@
-name: Lint
+name: Lint specification markdown file
 
 on:
   pull_request:
     types: [opened, reopened, synchronize, ready_for_review]
+    paths:
+      - 'spec/asyncapi.md'
 
 jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
       - name: Run linter
-        run: npx mdv spec/*.md
-
+        run: docker run -v $PWD:/workdir ghcr.io/igorshubovych/markdownlint-cli:v0.35.0 "spec/asyncapi.md"

.github/workflows/new-spec-release.yml

@@ -13,12 +13,12 @@ jobs:
       GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
     steps:
       - name: Checkout Current repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           path: spec
           ref: ${{ github.event.release.target_commitish }}
       - name: Checkout Another repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           repository: asyncapi/website
           path: website
@@ -32,7 +32,7 @@ jobs:
         run: |
           git checkout -b spec-release-${{github.event.release.tag_name}}
       - name: Check for previous spec file and remove it
-        uses: actions/github-script@v3
+        uses: actions/github-script@v6
         with:
           github-token: ${{ env.GITHUB_TOKEN }}
           script: |
@@ -53,14 +53,14 @@ jobs:
         run: |
           cp ../spec/spec/asyncapi.md ./pages/docs/reference/specification/${{github.event.release.tag_name}}.md
       - name: Remove Table of Contents from Spec
-        uses: actions/github-script@v4
+        uses: actions/github-script@v6
         with:
           github-token: ${{ env.GITHUB_TOKEN }}
           script: |
             const script = require('./spec/.github/scripts/remove-toc');
             script(`${{github.event.release.tag_name}}`);
       - name: Change the redirect file to point to latest spec
-        uses: actions/github-script@v3
+        uses: actions/github-script@v6
         if: ${{github.event.release.prerelease == false}}
         with:
           github-token: ${{ env.GITHUB_TOKEN }}
@@ -90,7 +90,7 @@ jobs:
 
             fs.writeFileSync("./website/public/_redirects", newRedirect);
       - name: Remove previous pre-release redirects in case of a new release
-        uses: actions/github-script@v3
+        uses: actions/github-script@v6
         with:
           github-token: ${{ env.GITHUB_TOKEN }}
           script: |
@@ -125,7 +125,7 @@ jobs:
 
             fs.writeFileSync("./website/public/_redirects", newRedirect);
       - name: Change the redirect file to point to specs
-        uses: actions/github-script@v3
+        uses: actions/github-script@v6
         with:
           github-token: ${{ env.GITHUB_TOKEN }}
           script: |

.github/workflows/update-spec.yaml

@@ -15,11 +15,11 @@ jobs:
       GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
     steps:
       - name: Checkout Current repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           path: spec
       - name: Checkout Another repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           repository: asyncapi/website
           path: website
@@ -43,7 +43,7 @@ jobs:
         run: |
           cp ../spec/spec/asyncapi.md ./pages/docs/reference/specification/${{ steps.latest_version.outputs.latest_tag }}.md
       - name: Remove Table of Contents from Spec
-        uses: actions/github-script@v4
+        uses: actions/github-script@v6
         with:
           github-token: ${{ env.GITHUB_TOKEN }}
           script: |

.markdownlint.yaml

@@ -0,0 +1,9 @@
+# MD013/line-length - Line length
+# We should keep it disabled as this line length limit do not maeke sense really
+MD013: false
+# MD033/no-inline-html - Inline HTML
+# We use HTML links in deadings all over the place. Probably this is why links in GitHub do not work, but that requires investingation if we can remove them really
+MD033: false
+# MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content
+# For now hard to say how that should be fixed as we have such duplicates like Fixed Fields all over the place
+MD024: false

CONTRIBUTING.md

@@ -243,6 +243,14 @@ A pull request can be merged if all the following conditions are met:
 * There is, at least, a mininum of 3 approvals from the [repository code owners](./CODEOWNERS).
 * Sufficient time has passed to let all code owners review the pull request. As of now, it should be a minimum of 1 week. If all code owners have already approved a pull request, it's ok not to wait for this period of time.
 
+## Linting specification document
+
+Always make sure that the specification markdown file has no markdown-related errors.
+
+Instead of waiting for GitHub Actions workflow to check markdown file, you can do it locally by calling the following docker command:
+```bash
+docker run -v $PWD:/workdir ghcr.io/igorshubovych/markdownlint-cli:v0.35.0 "spec/asyncapi.md"
+```
 
 ## References
 This document was adapted from the [GraphQL Specification Contribution Guide](https://github.com/graphql/graphql-spec/blob/main/CONTRIBUTING.md).