From 777f963354350a9b5c71e920292a41d74755c2f8 Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Sun, 24 Aug 2025 18:33:24 +0200 Subject: [PATCH] feat(doc): added markdown linting Signed-off-by: Frederic BIDON --- .github/workflows/doc-update.yml | 159 +++++++++++++++++++++++++ .github/workflows/go-test.yml | 4 +- .github/workflows/local-doc-update.yml | 17 +++ README.md | 36 +++--- 4 files changed, 197 insertions(+), 19 deletions(-) create mode 100644 .github/workflows/doc-update.yml create mode 100644 .github/workflows/local-doc-update.yml diff --git a/.github/workflows/doc-update.yml b/.github/workflows/doc-update.yml new file mode 100644 index 0000000..f51d5c7 --- /dev/null +++ b/.github/workflows/doc-update.yml @@ -0,0 +1,159 @@ +name: doc update check + +on: + workflow_call: + +# TODO: +# * [] markdown lint +# * [] spell checker + +permissions: + pull-requests: write + contents: read + +env: + comment-title: Markdown linter + +jobs: + markdown-changed: + # description: | + # This performs a markdown lint whenever documentation files change + runs-on: ubuntu-latest + outputs: + proceed: ${{ steps.changed-markdown-files.outputs.any_changed }} + all_changed_files: ${{ steps.changed-markdown-files.outputs.all_changed_files }} + steps: + - uses: actions/checkout@v5 + with: + ref: ${{ github.event.pull_request.head.sha }} + + - name: Get changed markdown files + uses: tj-actions/changed-files@v46 + id: changed-markdown-files + with: + files: '**/*.md' + + - name: Notify + run: | + echo "::notice::Detected some changed markdown files" + echo "${{ steps.changed-markdown-files.outputs.all_changed_files }}" + + lint-markdown: + needs: markdown-changed + if: needs.markdown-changed.outputs.proceed == 'true' + runs-on: ubuntu-latest + env: + lintreport: './markdownlint-report.txt' + outputs: + proceed: ${{ steps.report-exists.outputs.proceed }} + report: ${{ steps.report-exists.outputs.report }} + + steps: + - name: Checkout Repo + uses: actions/checkout@v5 + with: + ref: ${{ github.event.pull_request.head.sha }} + #ref: "refs/pull/${{ github.event.number }}/merge" # it's okay to pull the user's changes: we just scan md's + + - name: Run markdown linter + continue-on-error: true + id: markdownlint + uses: docker://avtodev/markdown-lint:v1.5 + with: + config: ./.github/.markdownlint.yml + args: '${{ needs.markdown-changed.outputs.all_changed_files }}' + output: '${{ env.lintreport }}' + + - name: Find previous PR comment + if: steps.markdownlint.outcome == 'success' + uses: peter-evans/find-comment@v3 + id: findcomment + with: + issue-number: ${{ github.event.pull_request.number }} + body-includes: ${{ env.comment-title }} + direction: last + + - name: Comment on success + if: steps.markdownlint.outcome == 'success' + id: congrats + uses: peter-evans/create-or-update-comment@v4 + with: + issue-number: ${{ github.event.pull_request.number }} + comment-id: ${{ steps.findcomment.outputs.comment-id }} + reactions: hooray + reactions-edit-mode: replace + body: | + ### ${{ env.comment-title }} + + Markdown looks good to me. Congrats! + + - name: Check lint report exists + if: ${{ steps.markdownlint.outcome != 'success' && hashFiles(env.lintreport) != '' }} + id: report-exists + run: | + echo 'report<> $GITHUB_OUTPUT + cat ${{ env.lintreport }}|sed -e '$a\' >> $GITHUB_OUTPUT + echo 'EOF' >> $GITHUB_OUTPUT + + if [[ "$(cat ${{ env.lintreport }}|wc -l)" != "0" ]] ; then + echo "proceed=true" >> $GITHUB_OUTPUT + echo "::notice::Detected some linting issues with changed markdown" + cat ${{ env.lintreport }}|sed -e '$a\' + else + echo "proceed=false" >> $GITHUB_OUTPUT + echo "::notice::No linting issues with changed markdown" + fi + + - name: Other linter errors + if: ${{ steps.markdownlint.outcome != 'success' && hashFiles(env.lintreport) == '' }} + run: | + echo "::error::markdown linter encountered an error" + exit 1 + + pr-comment: + needs: lint-markdown + if: needs.lint-markdown.outputs.proceed == 'true' + runs-on: ubuntu-latest + + steps: + - name: Format PR comment + id: commentformatter + uses: skills/action-text-variables@v1 + with: + template-vars: | + text='${{ needs.lint-markdown.outputs.report }}' + template-text: | + ### ${{ env.comment-title }} + + Some markdown linting issues were detected in the modified .md files. + + Perhaps they were already there before your changes. + + This check is advisory only and not blocking. Please help us adopt a nice markdown style. + + Markdown formatting rules are documented [here](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md). +
+ {{ text }} + + - name: Find previous PR comment + uses: peter-evans/find-comment@v3 + id: findcomment + with: + issue-number: ${{ github.event.pull_request.number }} + body-includes: ${{ env.comment-title }} + direction: last + + - name: Create or update PR comment + uses: peter-evans/create-or-update-comment@v4 + with: + issue-number: ${{ github.event.pull_request.number }} + comment-id: ${{ steps.findcomment.outputs.comment-id }} + reactions: confused + reactions-edit-mode: replace + body: ${{ steps.commentformatter.outputs.updated-text }} + edit-mode: replace + + - name: Notify + run: | + echo "::notice::Commented pull request ${{ github.event.pull_request.number }}" + echo "::debug::${{ steps.commentformatter.outputs.updated-text }}" diff --git a/.github/workflows/go-test.yml b/.github/workflows/go-test.yml index 2e3071a..93b4a50 100644 --- a/.github/workflows/go-test.yml +++ b/.github/workflows/go-test.yml @@ -34,7 +34,7 @@ jobs: echo "### Your changes to the go code look good. 👍" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY echo "> ℹī¸ INFO: we use [golangci-lint action](https://github.com/golangci/golangci-lint-action)" >> $GITHUB_STEP_SUMMARY - echo "> to lint any change to go code from master" >> $GITHUB_STEP_SUMMARY + echo "> to lint any change to go code from master." >> $GITHUB_STEP_SUMMARY unit_tests: name: Unit tests @@ -116,7 +116,7 @@ jobs: echo "### All tests completed. 👍" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY echo "> ℹī¸ INFO: we run unit tests in 6 different configurations of OS and go version." >> $GITHUB_STEP_SUMMARY - echo "> At this moment, we don't run architecture-specific test runs" >> $GITHUB_STEP_SUMMARY + echo "> At this moment, we don't run architecture-specific tests." >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY echo "| go version | OS | Result |" >> $GITHUB_STEP_SUMMARY echo "|------------|----|--------|" >> $GITHUB_STEP_SUMMARY diff --git a/.github/workflows/local-doc-update.yml b/.github/workflows/local-doc-update.yml new file mode 100644 index 0000000..b178b42 --- /dev/null +++ b/.github/workflows/local-doc-update.yml @@ -0,0 +1,17 @@ +name: doc update check + +# This workflow mimics how a go-openapi repo would typically invoke the common workflow. + +on: + pull_request_target: + paths: + - '**/*.md' + +permissions: + pull-requests: write + contents: read + +jobs: + test: + uses: ./.github/workflows/doc-update.yml + secrets: inherit diff --git a/README.md b/README.md index 0d268cd..5e45a29 100644 --- a/README.md +++ b/README.md @@ -10,26 +10,28 @@ NOTE: at this moment, it is difficult to share the golangci-lint config, so that ## Motivation It took a while, but we eventually managed to align all checks, tests and dependabot rules declared in the -family of go-openapi repos. +family of go-openapi repos. Now we'd like to be able to maintain, enrich and improve these checks without worrying too much about the burden to replicate it about a dozen times. ## Contemplated enhancements -* [x] enrich github actions UI with a job summary -* [] version common workflows, so we can limit the impact of a change -* [] verify that go.sum cache for tests works (should be enabled) -* [] share mono repo workflows (see github.com/go-openapi/swag/.github/workflows) -* [] manage somehow to share golangci config (with local merge) -* [] manage somehow to share / replicate dependabot config -* [] add markdown linting for docs -* [] golangci-lint: check valid PR comments etc -* [] add spellcheck for docs (and code?) -* [] use non-blocking, scheduled, proactive full linting to check for the impact of new linters, new go versions etc -* [] (possibility) take over hugo & doc gen part from go-swagger -* [] (possibility) take over release part from go-swagger -* [] produce hugo github page with all latest tagged versions (incl. mono repo) -* [] add bot to filter PRs, issues -* [] check with github API that all repo settings (branch protection rules, etc) are identical -* [] comment PRs and issues +In no particular order: + +* [x] ui: enrich github actions UI with a job summary +* [x] doc: add markdown linting for docs +* [ ] doc: add spellcheck for docs (and code?) +* [ ] version common workflows, so we can limit the impact of a change +* [ ] build: verify that go.sum cache for tests works (should be enabled) +* [ ] share mono repo workflows (see github.com/go-openapi/swag/.github/workflows) +* [ ] lint: manage somehow to share golangci config (with local merge) +* [ ] deps: manage somehow to share / replicate dependabot config +* [ ] lint: golangci-lint: check valid PR comments etc +* [ ] lint: use non-blocking, scheduled, proactive full linting to check for the impact of new linters, new go versions etc +* [ ] doc: (possibility) take over hugo & doc gen part from go-swagger +* [ ] (possibility) take over release part from go-swagger +* [ ] doc: produce hugo github page with all latest tagged versions (incl. mono repo) +* [ ] add bot to filter PRs, issues +* [ ] check with github API that all repo settings (branch protection rules, etc) are identical +* [ ] comment PRs and issues