diff --git a/.github/styles/suse-vale-styleguide b/.github/styles/suse-vale-styleguide new file mode 160000 index 00000000000..06f144fdfc7 --- /dev/null +++ b/.github/styles/suse-vale-styleguide @@ -0,0 +1 @@ +Subproject commit 06f144fdfc78c769a9d86db5a6c550d7e6fc17da diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml new file mode 100644 index 00000000000..a695beac412 --- /dev/null +++ b/.github/workflows/vale.yml @@ -0,0 +1,53 @@ +# This action gets all changed markdown files in /docs and /versioned_docs using tj-actions/changed-files@v42 +# It compares new commits in the PR with the base commit (github.event.pull_request.base.sha) +# It checks if no markdown files are changed +# It shows a count of markdown files and lists all changed markdown files +# It uses Vale (https://vale.sh/docs/vale-cli/installation/) to provide feedback base off the SUSE Style Guide / OpenSUSE style rules (https://github.com/openSUSE/suse-vale-styleguide) + +name: Style check +on: [pull_request] + +jobs: + vale-lint: + name: runner / vale + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # OR "2" -> To retrieve the preceding commit. + submodules: true + - name: Get all changed markdown files + id: changed-markdown-files + uses: tj-actions/changed-files@v42 + with: + # Avoid using single or double quotes for multiline patterns + files: | + docs/** + versioned_docs/** + separator: "," + base_sha: ${{ github.event.pull_request.base.sha }} + env: + ALL_CHANGED_FILES: ${{ 0 }} + - name: No files changed? + if: steps.changed-markdown-files.outputs.any_changed == 'false' + run: | + echo "No files changed" + echo "ALL_CHANGED_FILES=$ALL_CHANGED_FILES" >> $GITHUB_ENV + - name: List all changed files markdown files + if: steps.changed-markdown-files.outputs.any_changed == 'true' + env: + ALL_CHANGED_FILES: ${{ steps.changed-markdown-files.outputs.all_changed_files }} + ALL_CHANGED_FILES_COUNT: ${{ steps.changed-markdown-files.outputs.all_changed_files_count }} + SHA: ${{ github.head_ref }} + HEAD: ${{ github.base_ref }} + run: | + echo "Total Files Changed:" ${ALL_CHANGED_FILES_COUNT} + echo ${ALL_CHANGED_FILES} + echo "ALL_CHANGED_FILES=$ALL_CHANGED_FILES" >> $GITHUB_ENV + - uses: errata-ai/vale-action@v2.1.0 + if: steps.changed-markdown-files.outputs.any_changed == 'true' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + separator: ", " + files: ${{ env.ALL_CHANGED_FILES }} \ No newline at end of file diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 00000000000..1af7b495ba5 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule ".github/styles/suse-vale-styleguide"] + path = .github/styles/suse-vale-styleguide + url = https://github.com/openSUSE/suse-vale-styleguide diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 00000000000..84cf4b55591 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,7 @@ +StylesPath = .github/styles + +[formtats] +mdx = md + +[*.md] +BasedOnStyles = suse-vale-styleguide \ No newline at end of file diff --git a/README.md b/README.md index 6e9adbc8dac..ca3db799c77 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,17 @@ The file paths in the repo correspond to the URLs for pages on the docs website. ### Style & Formatting -The docs are written in [Markdown](https://www.markdownguide.org/getting-started/). We refer to the Microsoft [style guide](https://learn.microsoft.com/en-us/style-guide/welcome/) and use standard American English. Many pages are also available in Simplified Chinese. +The docs are written in [Markdown](https://www.markdownguide.org/getting-started/). We use standard American English and many pages are also available in Simplified Chinese. + +Moving forward, we are referring to the SUSE [style guide](https://documentation.suse.com/style/current/pdf/style-guide_en.pdf). The **Style check / runner / vale (pull_request)** check used [Vale](https://vale.sh/) to make style and grammar suggestions for new or updated documentation based on the SUSE style guide. To review these suggestions when working on a PR: + +1. Select the details of the **Style check / runner / vale (pull_request)** check. +1. In the logs, go to **Run errata-ai/vale-action@v2.1.0** and select **Running vale with reviewdog 🐶 ...** to view the suggestions. +1. New or updated files are checked against the SUSE style guide. Suggestions have the following format: '{"message": "[suse-vale-styleguide.Rule] Rule description", "location": {"path": "file-path", "range": {"start": {"line": , "column": }}}, "severity": " "}' + + For example: '{"message": "[suse-vale-styleguide.Usage] Use 'certain' instead of 'some'", "location": {"path": "docs/contribute-to-rancher.md", "range": {"start": {"line": 3, "column": 132}}}, "severity": "WARNING"}' + +1. Incorporate the suggestions when possible and appropriate. Every docs page contain metadata in the first few lines: