I don’t like hardcoded versions. Are there alternatives?

Thanks for the feedback @EwoutH! I've addressed your comments:
Hardcoded version: Replaced manual installation with official errata-ai/[email protected]

Let me know if you'd like any other adjustments!

Do we both need to be in GitHub actions and Pre-commit? If not, I prefer only being in pre-commit.

There is a technical catch with using only pre-commit.ci:

The pre-commit.ci bot runs in an isolated environment and cannot run vale sync to download the external Google styles. This causes Runtime Error unless the styles are present locally.

If we want to use only pre-commit, I will need to commit the entire Google style definition folder (inside .github/styles/Google) directly into the repository so the bot can access them.

Why I chose the Action: I saw that in PR #2568, there was hesitation about adding the Microsoft style files directly to the repo. To respect that preference and keep the repo clean, I used a GitHub Action to download the styles on the fly, rather than committing them.

Are you comfortable with committing the Google style files (~33 YAML files) to the repository? If so, I can switch to pre-commit only. Otherwise, the GitHub Actions workflow provides a cleaner solution.
Let me know your preference!

So a GitHub Action can dynamically load them while pre-commit cannot?

Yes, exactly.

• GitHub Actions allows us to run shell commands, so the workflow I added explicitly runs vale sync to download the styles before the check starts.
• pre-commit.ci is a stricter, sandboxed environment. It does not run arbitrary setup commands (like vale sync) before the hooks. It expects all configuration files to be present in the repository itself.

That is why the Action works 'out of the box' while pre-commit.ci fails unless we commit the style files.

Right, so in our case, what does vale in pre-commit do?

In our current setup, Vale in pre-commit acts as an immediate feedback tool. Provided the developer has run vale sync once on their machine, pre-commit catches style errors before they push code. This saves them from waiting for CI to fail. We keep the pre-commit hook solely for the benefit of local developers (so they can lint while they code). We rely on the GitHub Action to perform the actual "official" check on the server.

I don’t understand how vale is off here, but there are still changes in the document

I first made vale run through the file to identify any spelling errors in the file. Then I turned vale off for that file to avoid noise from false positives, specifically regarding spell checking.

The Issue:
Vale's default spell checker treats technical terms (e.g., variable names, module paths, library-specific jargon) as spelling errors if they aren't in its standard dictionary. Since HISTORY.md is a log of code changes, it is naturally full of these terms.

What I tried first:
I initially attempted to fix this by building a project-specific vocabulary (accept.txt), adding valid technical terms to it so Vale would recognize them.

Why that didn't work:
I quickly found that the number of unique variable names and technical terms in the history log is massive. Maintaining an accept.txt list for every single new parameter or method mentioned in the changelog would become a significant maintenance burden (the file would grow indefinitely and require constant updates).

Since we already use codespell (which is better tuned for codebases), I decided it was cleaner to rely on codespell for catching typos in these specific files and use Vale purely for enforcing style/prose in the documentation, where it shines. If you need vale to be enabled in those 2 files, I can make changes to the file and enable it.

Would it make sense to limit it to certain folders?

Yes, we can certainly do that.

Currently, the configuration targets the docs/ folder AND *.md (files in the root directory).

If we limit Vale strictly to the docs/ folder:

• Pro: It automatically ignores HISTORY.md and CODE_OF_CONDUCT.md without needing any exclude rules.
• Con: It would stop linting the main README.md of the project (since it sits in the root), and that is often the most visible file for new users.

I stuck with the current approach (checking root files + manual excludes) specifically to keep the main README.md covered.

Let’s start in this PR with /docs only, and then we can discuss if we want to extend it later.

I have updated the PR to include only the changes in /docs.

@EwoutH, can you confirm that this PR is now ready to be merged?