vale: Unwanted warnings raised with version 2.29.4

Check for existing issues

Completed

Environment

I’m using value through the github action errata-ai/vale-action@reviewdog but I think it is appropriate to open an issue here as my problem arises when a change the vale version.

Here is my action setting:

  doc-style:
    name: "Check documentation style"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
  
      - name: Running Vale
        uses: errata-ai/vale-action@reviewdog
        env:
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
        with:
          files: doc
          reporter: github-pr-check
          level: error
          filter_mode: nofilter
          fail_on_error: true
          vale_flags: "--config=doc/.vale.ini"

and my .vale.ini contains

StylesPath = "styles"
MinAlertLevel = warning
IgnoredScopes = code, tt
SkippedScopes = script, style, pre, figure
WordTemplate = \b(?:%s)\b
Packages = Google
Vocab = perso # This accepts PEP 8 (cf my rst file context)

[*.{rst}]

BasedOnStyles = Vale, Google
TokenIgnores = (:.*:`.*`)

Google.WordList = NO
Google.Colons = NO

Describe the bug / provide steps to reproduce it

The error I’m facing is that when vale works on my .rst file, the google rule regarding Heading is triggered when it shouldn’t.

Here is my rst file

PEP 8
=====
blabla

Imports
-------
blabla

Import location
~~~~~~~~~~~~~~~
blabla

and the associated errors

 {"message": "[Google.Headings] 'PEP 8' should use sentence-style capitalization.", ..., "severity": "WARNING"}
 {"message": "[Google.Headings] 'Imports' should use sentence-style capitalization.", ... , "severity": "WARNING"}
 {"message": "[Google.Headings] 'Import location' should use sentence-style capitalization.", ... , "severity": "WARNING"}

While I though that this error might be related to https://github.com/errata-ai/vale/discussions/702, using Google.Headings = NO didn’t solve my issue. However, this warnings are no longer raised when I constraint the vale github action to use the version “2.29.3” (latest is “2.29.4”).

About this issue

Original URL
State: closed
Created 9 months ago
Reactions: 1
Comments: 15 (5 by maintainers)

Commits related to this issue

BUGFIX: constraint vale version to remove warning Problem : warnings are raised because titles are caught by Google Heading rule (which should not happen) Constraining vale to the previous latest ve... — committed to ansys/pyansys-dev-guide by SMoraisAnsys 9 months ago

Most upvoted comments

The underlying data structure for accept.txt is not sorted, so having multiple (differently-cased) entries for the same term can result in nondeterministic behavior (as you saw above).

Your accept.txt can be re-written as:

[Rr]eviewdog
[Rr]unbook
[Ss]trikethrough
Artifactory
Backstage
Code
CODEOWNERS
DevEx
Diataxis
discoverability
GitHub
Kroki
Markdown
MkDocs
PDF
PlantUML
SharePoint
Spotify
Studio
TechDocs
Vale
Visual
Volvo Cars

You should generally have one entry per term.

jdkato on Oct 19, 2023

I’ve updated our action to use version 2.29.5 however part of the error is still here :

  {"message": "[Google.Headings] 'PEP 8' should use sentence-style capitalization.", ... , "severity": "WARNING"}

Note: errors associated to

Imports
-------
blabla

Import location
~~~~~~~~~~~~~~~
blabla

are no longer present 👍

SMoraisAnsys on Oct 16, 2023

Running vale on the same Markdown file every 3 seconds produces different results. Very odd behaviour:

❯ while true; do vale docs/technical-writing-101/documentation-topic-types/runbook.md; date; sleep 3; done
✔ 0 errors, 0 warnings and 0 suggestions in 1 file.
Thu Oct 19 14:27:49 CEST 2023
✔ 0 errors, 0 warnings and 0 suggestions in 1 file.
Thu Oct 19 14:27:53 CEST 2023
✔ 0 errors, 0 warnings and 0 suggestions in 1 file.
Thu Oct 19 14:27:56 CEST 2023

 docs/technical-writing-101/documentation-topic-types/runbook.md
 8:3  warning  'Runbook information type'      Volvo-Cars.Headings
               should use sentence-style
               capitalization.

✖ 0 errors, 1 warning and 0 suggestions in 1 file.
Thu Oct 19 14:27:59 CEST 2023
✔ 0 errors, 0 warnings and 0 suggestions in 1 file.
Thu Oct 19 14:28:03 CEST 2023
✔ 0 errors, 0 warnings and 0 suggestions in 1 file.
Thu Oct 19 14:28:06 CEST 2023

 docs/technical-writing-101/documentation-topic-types/runbook.md
 8:3  warning  'Runbook information type'      Volvo-Cars.Headings
               should use sentence-style
               capitalization.

✖ 0 errors, 1 warning and 0 suggestions in 1 file.
Thu Oct 19 14:28:09 CEST 2023
✔ 0 errors, 0 warnings and 0 suggestions in 1 file.
Thu Oct 19 14:28:12 CEST 2023

 docs/technical-writing-101/documentation-topic-types/runbook.md
 8:3  warning  'Runbook information type'      Volvo-Cars.Headings
               should use sentence-style
               capitalization.

✖ 0 errors, 1 warning and 0 suggestions in 1 file.
Thu Oct 19 14:28:16 CEST 2023

 docs/technical-writing-101/documentation-topic-types/runbook.md
 8:3  warning  'Runbook information type'      Volvo-Cars.Headings
               should use sentence-style
               capitalization.

✖ 0 errors, 1 warning and 0 suggestions in 1 file.
Thu Oct 19 14:28:19 CEST 2023
✔ 0 errors, 0 warnings and 0 suggestions in 1 file.
Thu Oct 19 14:28:22 CEST 2023
✔ 0 errors, 0 warnings and 0 suggestions in 1 file.
Thu Oct 19 14:28:25 CEST 2023

 docs/technical-writing-101/documentation-topic-types/runbook.md
 8:3  warning  'Runbook information type'      Volvo-Cars.Headings
               should use sentence-style
               capitalization.

✖ 0 errors, 1 warning and 0 suggestions in 1 file.
Thu Oct 19 14:28:29 CEST 2023
^C%

The offending word Runbook is in accept.txt:

❯ cat .vale/volvo-cars-style-guide/styles/Vocab/Volvo-Cars/accept.txt
Artifactory
Backstage
CODEOWNERS
DevEx
Diataxis
GitHub
Kroki
Markdown
MkDocs
PDF
PlantUML
Reviewdog
Runbook
TechDocs
Vale
Visual
Studio
Code
Volvo Cars
discoverability
reviewdog
runbook
Runbook
SharePoint
Spotify
strikethrough
Strikethrough

pwalleni on Oct 19, 2023

Could you share your accept.txt? Do you have multiple case variations of “TechDocs”?

Hi @jdkato. Thanks for the support. Yes, there are techdocs and TechDocs: https://gist.github.com/pwalleni/c56a849bfb736e1f32bb4104566681a4

pwalleni on Oct 17, 2023

If you update to the latest version of the Google style (v0.4.2) either by running vale sync (locally) or re-running the action workflow, this should be resolved too.

jdkato on Oct 16, 2023