experimental

.github/workflows/TODO.md

@@ -1,5 +1,14 @@
 Evaluate:
 
+* markdownlint
+  * assessment: go
+  * used by opentelemetry/opentelemetry-go
+  * packaged as github action
 * misspell
 * spellcheck
 * govulncheck
+* [x] godoc-lint:
+  * assessment: no go
+  * too simplistic: no real value added
+  * not integrated into golangci's suite of linters
+  * no packaged github action

.github/workflows/markdown.yml

@@ -10,59 +10,93 @@ permissions:
   contents: read
 
 jobs:
-
-  lint-markdown:
-    runs-on: ubuntu-latest
+  markdown-changed:
+    outputs:
+      proceed: ${ steps.changed-markdown-files.outputs.any_changed }
     steps:
     - name: Checkout Repo
       uses: actions/checkout@v4
 
-    - name: Get all changed markdown files
+    - name: Get changed markdown files
       id: changed-markdown-files
       uses: tj-actions/changed-files@v45
       with:
         # Avoid using single or double quotes for multiline patterns
         files: |
           **/*.md
 
-    - name: "DEBUG List all changed files markdown files"
-      if: steps.changed-markdown-files.outputs.any_changed == 'true'
-      env:
-        ALL_CHANGED_FILES: 
-      run: |
-        for file in ${ALL_CHANGED_FILES}; do
-          echo "$file was changed"
-        done
+  lint-markdown:
+    needs: markdown-changed
+    if: needs.markdown-changed.outputs.proceed == 'true'
+    runs-on: ubuntu-latest
+    env:
+      lintreport: "./report.txt"
+    outputs:
+      proceed: ${{ steps.report-exists.proceed }}
+      report: ${{ steps.report-exists.report }}
+
+    steps:
+    - name: Checkout Repo
+      uses: actions/checkout@v4
 
     - name: Run markdown linter
+      if: steps.changed-markdown-files.outputs.any_changed == 'true'
+      continue-on-error: true
       id: markdownlint
       uses: docker://avtodev/markdown-lint:v1
       with:
         config: .markdownlint.yml
         args: '${{ steps.changed-markdown-files.outputs.all_changed_files }}'
-        output: ./lintreport.txt
+        output: ${{ env.lintreport }}
+
+    - name: Comment on success
+      if: ${{ success() }}
+      id: congrats
+      uses: peter-evans/create-or-update-comment@v4
+      with:
+        issue-number: ${{ github.event.pull_request.number }}
+        body: |
+          Markdown looks good to me. Congrats!
 
-    - name: Retrieve report as a variable
-      if: ${{ failure() && steps.markdownlint.outcome == 'failure' }}
-      id: conveyor
+    - name: Check lint report exists
+      if: ${{ failure() && steps.markdownlint.outcome == 'failure' && hashFiles(env.lintreport) != "" }}
+      id: report-exist
       run: |
-        echo "::set-output name=text::$(cat ./lintreport.txt)"
+        echo "proceed=true" >> $GITHUB_OUTPUT
+        echo "report=$(cat ${{ env.lintreport }})" >> $GITHUB_OUTPUT
 
+  pr-comment:
+    needs: lint-markdown
+    if: ${{ needs.lint-markdown.proceed == 'true' && needs.lint-markdown.report != '' }}
+    env:
+      comment-title: Markdown linting issues detected in modified files
+
+    steps:
     - name: Format PR comment
-      if: ${{ failure() && steps.markdownlint.outcome == 'failure' }}
       id: commentformatter
       uses: skills/action-text-variables@v1
       with:
         template-vars: |
-            text=$${{ steps.conveyor.outputs.text }}
+            text=${{ steps.conveyor.outputs.report }}
         template-text: |
-            ## Markdown linting issues detected in modified files
+            ### ${{ env.comment-title }}
+            This check is advisory and is not blocking. Please adopt a nice markdown style.
+
+            Markdown rules formatting rules are documented [here](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md).
 
             {{ text }}
 
-    - name: Create PR comment
-      if: ${{ failure() && steps.markdownlint.outcome == 'failure' }}
+    - name: Find previous PR comment
+      uses: peter-evans/find-comment@v3
+      id: findcomment
+      with:
+        issue-number:  ${{ github.event.pull_request.number }}
+        body-includes: ${{ steps.conveyor.outputs.report }}
+        direction: last
+
+    - name: Create or update PR comment
       uses: peter-evans/create-or-update-comment@v4
       with:
         issue-number: ${{ github.event.pull_request.number }}
-        body: $${{ steps.commentformatter.outputs.updated-text }}
+        comment-id: ${{ steps.findcomment.outputs.comment-id }}
+        body: ${{ steps.commentformatter.outputs.updated-text }}

.markdownlint.yml

@@ -1,8 +1,10 @@
+# See rules documentation: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+
 # Default state for all rules
 default: true
 
-# ul-style
-MD004: false
+# ul-style # default: consistent
+# MD004: false
 
 # hard-tabs
 MD010: false
@@ -15,7 +17,7 @@ MD024:
   siblings_only: true
 
 #single-title
-MD025: false
+#MD025: false
 
 # ol-prefix
 MD029:

README.md

@@ -13,3 +13,5 @@ Shared errors and error interface used throughout the various libraries found in
 # should raise an issue
 
 # should raise another issue
+
+## blah blah