Defining a Vale onboarding strategy

Embracing a linter in a project is a long journey. The full Vale report can be discouraging at first. Remember that:

You are in charge: review the report and decide what is useful to you.
The styles are not perfect or complete.
Assess the maturity of the project.

Prerequisites

Assess the project maturity

Zero Vale errors

The project is compliant with the RedHat style. Consider integration with a continuous integration service using the defaults from the vale-at-red-hat repository.

Under 100 Vale errors

The project is almost compliant with the RedHat style. Consider integration with a continuous integration service using the defaults from the vale-at-red-hat repository. Consider massively fixing the few errors.

Over 100 Vale errors

The project is big or poorly compliant with the RedHat style. Consider further investigation to understand the issue.

Start small

To onboard a collection of repositories, start by the repository with the smallest word count. See Generating extended Vale alerts reports

Focus on errors

Report only errors. Don’t report warnings and suggestions.
```
$ vale --minAlertLevel=error .
```

Expect false positives

The RedHat style has been thoroughly tested on a corpus of 113000 words. You can expect false positives when applying the style to a new corpus. Consider ✨ Join Us: Contribute Today! ✨ to the style.

Collect data

Generating extended Vale alerts reports
Use the results to identify the rule creating the most errors, and work on that rule. Most probably, start with the Spelling rule.
Report alerts for one single rule. Maybe use custom output templates to generate a custom report. See Vale documentation - JSON output of checks and Vale documentation - --output. Consider aggregating alerts to identify the most common. Examine the report to distinguish legit alerts from false positives. Use the curated list of false positives to report an issue.

For example, for the Spelling rule, create a report containing the list of all words reported by the Spelling rule, and count their occurrences. Use that list to differentiate false positives from legit errors. Use the curated list to report an issue.

Fix the alerts

Run campaigns focused on one target such as: fix all errors, fix all occurrences of a given rule.

Disable a rule that is irrelevant in the file context. See: Vale - Markup-based configuration

pass:[<!-- vale RedHat.Spelling = NO -->]

The Spelling rule is ignored for this line.

pass:[<!-- vale RedHat.Spelling = YES -->]

The Spelling rule is active for this line.

Display less alerts without changing the configuration file

Display only errors. Don’t display warnings and suggestions.
```
$ vale --minAlertLevel=error .
```
Display only errors and warnings. Don’t display suggestions.
```
$ vale --minAlertLevel=warning .
```

Contributing to the vale-at-red-hat repository

Decrease the number of alerts requesting Adding Vale to a project

Creating a vocabulary for a project
Altering rules severity or disabling rules for the project. See Adding Vale to a project and Vale documentation - configuration.
```
RedHat.Annotations = NO
RedHat.Slash = warning
RedHat.Usage = suggestion
```
Creating an additional style for the project. See Adding Vale to a project

Additional resources