How do we scope rules, such as ReleaseNotes.yml, to only run on specific files?

[rolfedh]

Suppose that I've created a rule for the SupplementaryStyleGuide style, called ReleaseNotes.yml, that I only want to run on release notes. I don't want it to run everywhere because it might generate too many false positives. How might we do this?

[rolfedh]

One way might be to create a "targeted" style, such as ReleaseNotes, that contains additional rules for release notes. Then, you enable that style by adding a special .vale.ini file to the /releasenotes directory. This /releasenotes/.vale.ini file overrides any other .vale.ini file in your system. It differs from the other .vale.ini files that it overrides by adding ReleaseNotes to the following line:
BasedOnStyles = CheDocs,IBM,Vale,SupplementaryStyleGuide,ReleaseNotes.

[rolfedh]

For this ^^^ approach, we also need to manage whether we add .vale.ini file to our doc repos:

• If you only want to do this locally, add .vale.ini to the .gitingore file in your doc repo. That way, git won't pick up .vale.ini and add it to your staged changes when you prepare to push new files to your repo.
• If you want to add .vale.ini to your doc repo, consult your documentation team to make sure other Vale users know about it.

[rolfedh]

One drawback of this approach is that it takes the ReleaseNotes.yml rule, which is based on the Supplementary Style Guide, out of the SupplementaryStyleGuide folder. Keeping track of these types of exceptions could become unwieldy.
I would prefer to keep ReleaseNotes.yml rule in the SupplementaryStyleGuide folder and find a way to switch it on or off for a particular context. How might we do that?

[michaelryanpeter]

When I first started exploring Vale more than a year ago, I remember being able to call styles other than the default from the command line. The style had be in your $PATH, but you could turn it on from the command line.

This would work if you had a separate ReleaseNotes style folder.

Unfortunately, I can't find reference to this in the documentation. I was playing with a couple of linters at the time, so there is a good chance I am remembering a different linter. 🤷

[michaelryanpeter]

In the interest of keeping ReleaseNotes.yml in the SSG style, could you ignore ReleaseNotes.yml in the main folder and turn it on for /docs/release-notes/? This might be possible with the BasedOnStyles rule (https://docs.errata.ai/vale/config).

[michaelryanpeter]

I will play around with this and see if I can come up with something that works by our next meeting.

[michaelryanpeter]

See issue #33

[michaelryanpeter]

I will try to get a proof-of-concept by next week.

[michaelryanpeter]

https://docs.errata.ai/vale-server/concepts/config#basedonstyles

The documentation uses the example Style1.Rule1 = NO. Style1.Rule is the rule defined by <path/to/vale/>.vale/styles/Style1/Rule1.yml. The file <path/to/vale/>.vale/styles/IBM/ReleaseNotes.yml defines the rule IBM.ReleaseNotes.

For OpenShift release notes, open the file .vale.ini in your main repository. Add IBM.ReleaseNotes = NO below BasedOnStyles = IBM. Copy your .vale.ini to the release_notes folder and remove IBM.ReleaseNotes = NO.

The file <path/to/vale/>.vale/styles/IBM/ReleaseNotes.yml defines the rule IBM.ReleaseNotes.

[themr0c]

Some ideas:

• To distribute the rule in the RedHat style: leverage the alert level. Use level: suggestion in the rule, with a message that specifies that the rule applies only on release notes content. See: https://docs.errata.ai/vale/styles. Consider disabling the rule in the default vale configuration that we distribute.

Use one of these techniques to change the alert level of the rule for release notes:

• If the project contains mixed content and a specific directory contains release notes content, leverage the vale configuration file search process: add a vale configuration in the folder containing the release notes to enable specific rules or styles for the directory. See: https://docs.errata.ai/vale/config#search-process.

Vale expects its configuration to be in a file named .vale.ini or _vale.ini. It'll start looking for this file in the same folder as the file that's being linted. If it can't find one, it'll search up to 6 levels up the file tree. After 6 levels, it'll look for a global configuration file in the OS equivalent of $HOME (see below).

• To keep a unique vale configuration, leverage the glob pattern. https://docs.errata.ai/vale/config#format-specific-settings