Skip to content

Contribute to the Vale at Red Hat project

Learn how to contribute to the Vale at Red Hat project. This guide covers the repository structure, contribution workflow, and how to extend Vale by adding new words to the spelling rule or creating custom style rules. Whether you’re fixing bugs, adding new rules, or improving documentation, this guide will help you get started.

Join us! ✨

Hello! We’re happy you’re thinking about joining our project. Every bit helps, whether you’re fixing a typographical error, suggesting an improvement, or just getting to know the community. Got questions or need help? Ask us in the Slack channel #vale-at-red-hat, in the CoreOS workspace.

There are many ways you can help:

  • Make our docs better: Use Vale to help make our documentation clearer. Check out how to set Vale up here: Installing Vale CLI.

  • Tell us what you think: Let us know if something doesn’t work right or if you have a great idea. Go here to share your thoughts: Report issues and request enhancements.

  • Chat with us: Come talk to us on Slack in our chat room #vale-at-red-hat.

  • Share your work: Do you want to contribute changes? Please share it with us by following this guide: Git forking workflow.

  • Add your touch: Interested in adding rules or styles? Learn how here: Extending Styles.

Vale at Red Hat repository

The vale-at-red-hat repository has resources to validate language in documentation projects with Vale:

Additional resources

Updating the Red Hat dictionary

The Red Hat dictionary is a Hunspell-format dictionary that contains technical terms, product names, and Red Hat-specific jargon. When a word that should not get caught in the spelling filter is missing from the dictionary and is common enough to benefit all Red Hat documentation projects, you can add it to the dictionary wordlist.

Note

For project-specific terms that are unlikely to benefit other projects, use a project vocabulary instead. See Creating a vocabulary for a project.

Prerequisites
Procedure

  1. Open the wordlist file .vale/styles/RedHat/dictionaries/wordlist.txt in a text editor.

  2. Add the new word as plain text on a new line. You do not need to sort entries, add flags, or maintain a word count.

    The build script handles everything automatically:

    • Plural detection: If you add both the singular and plural forms (for example, API and APIs), the build script detects the relationship and consolidates them with the appropriate Hunspell flag.

    • Auto-capitalization: Lowercase words automatically get a title case counterpart in the dictionary. For example, adding spyre also generates Spyre.

    • Possessive forms: Capitalized words automatically get possessive forms (for example, Docker also generates Docker’s).

    For proper nouns and acronyms, use the exact casing you need, such as Docker or AWS.

    Lines starting with # are treated as comments and blank lines are ignored.

    Example entries
    API
APIs
Kubernetes
spyre
Docker

  3. Run the build script to regenerate the dictionary:

    $ python3 tools/build-dictionary.py

  4. Verify the spelling rule works correctly:

    $ vale --config=.vale.ini <file_containing_word>

  5. Add, commit, and push both wordlist.txt and en_US-RedHat.dic.

  6. Request a review or help in the Slack channel #vale-at-red-hat, in the CoreOS workspace.

Updating the affix file

The affix file .vale/styles/RedHat/dictionaries/en_US-RedHat.aff defines the morphology rules that the dictionary flags reference. In most cases, you do not need to modify this file. The build script (tools/build-dictionary.py) generates the appropriate flags automatically based on the plural forms it detects in the wordlist.

The current affix file defines:

  • S flag: Plural suffix rules that handle standard English pluralization patterns (-s, -es, -ies).

  • P flag: Possessive suffix rules that add 's to words not ending in s, or just ' to words ending in s (for example, Kubernetes').

Example affix file structure
SET UTF-8

# Plural suffix flag
SFX S Y 4
SFX S y ies [^aeiou]y
SFX S 0 s   [aeiou]y
SFX S 0 es  [sxzh]
SFX S 0 s   [^sxzhy]

# Possessive suffix flag
SFX P Y 2
SFX P 0 's [^s]
SFX P 0 ' [s]
Additional resources

Extending styles in the vale-at-red-hat repository

The vale-at-red-hat repository is an open source project maintained and developed by volunteers. If you want to contribute to the Vale at Red Hat project, feel free to open a PR.

Note

If you use a custom Vale rule set in your Red Hat project, consider adding it to the vale-at-red-hat repository.

Prerequisites
Procedure

  1. Configure the rule in the styles folder: .vale/styles/<Style>/<StyleName>.yml.

  2. Configure the test fixtures in the fixtures folder: .vale/fixtures/<Style>/<StyleName>/testinvalid.adoc|testvalid.adoc

  3. Run the vale command in the test fixtures folder to ensure that the rule triggers as you expect, for example:

    $ vale .
    Example output
     testinvalid.adoc
 2:1  error  Quoted ID value is not closed.  AsciiDoc.ClosedIdQuotes
 6:1  error  Quoted ID value is not closed.  AsciiDoc.ClosedIdQuotes

✖ 2 errors, 0 warnings and 0 suggestions in 2 files.

  4. Add, commit and push your changes.

  5. Request a review or help in the Slack channel #vale-at-red-hat, in the CoreOS workspace.

Additional resources