Skip to content

Conversation

@jstirnaman
Copy link
Contributor

@jstirnaman jstirnaman commented Feb 5, 2026

This PR updates and improves vale.sh rules in preparation for enabling Vale to run in PR checks and CI.

Updates vale and extensions
Add filters to prevent false positives on:

  • URL paths (e.g., /api/v2/write, /kapacitor/v1/api/v2/tasks)

  • Full URLs (http/https)

  • Shortcode attribute values (endpoint="...", method="...", etc.)

  • Add scope exclusions for code blocks (~code) and inline code (~raw) to prevent flagging code syntax.

  • Disable Vale.Terms to prevent false positives from URLs/paths

  • Create InfluxDataDocs.Units rule that allows duration literals (30d, 24h)
    while still validating byte units (GB, TB)

  • Disable write-good.TooWordy for technical terms (aggregate, expiration)

  • Add TokenIgnores for URL paths and inline code patterns

  • Expand spelling ignore list with technical terms (subprocess, CPUs, etc.)

  • Sync Google style packages via vale sync

Documentation improvements:

  • Add new vale-linting skill with comprehensive workflow
  • Update content-editing skill with Vale section
  • Enhance ci-automation-engineer agent with Vale expertise
  • Add Vale troubleshooting to copilot-instructions.md
  • Add shell command permissions to settings.json

Reduces Vale warnings from 794 to 187 (76% reduction) while keeping style validation active.

@jstirnaman jstirnaman force-pushed the claude/phase2-vale-improvements-cMYcc branch from 5000085 to 75d7c4c Compare February 6, 2026 10:28
…ance

Spelling improvements:
- Exclude fenced code blocks (~code) and inline code (~raw) from checking
- Add filters for URL paths, full URLs, and shortcode attributes
- Prevents false positives on code syntax and API endpoints

Capitalization improvements:
- Add InfluxDB product exceptions (InfluxDB, InfluxQL, Telegraf, etc.)
- Add common technical acronyms (API, CLI, SQL, HTTP, JSON, etc.)
- Add cloud provider names (AWS, GCP, Azure, S3)
- Add link to Google style guide for sentence case headings

Aligns with Google Developer Documentation Style Guide:
https://developers.google.com/style/capitalization

https://claude.ai/code/session_0173AuWPoy6UXiatCMGz4W7h
@jstirnaman jstirnaman force-pushed the claude/phase2-vale-improvements-cMYcc branch from 7f8a775 to 7d5898d Compare February 6, 2026 17:41
…skill

- Disable Vale.Terms to prevent false positives from URLs/paths
- Create InfluxDataDocs.Units rule that allows duration literals (30d, 24h)
  while still validating byte units (GB, TB)
- Disable write-good.TooWordy for technical terms (aggregate, expiration)
- Add TokenIgnores for URL paths and inline code patterns
- Expand spelling ignore list with technical terms (subprocess, CPUs, etc.)
- Sync Google style packages via vale sync

Documentation improvements:
- Add new vale-linting skill with comprehensive workflow
- Update content-editing skill with Vale section
- Enhance ci-automation-engineer agent with Vale expertise
- Add Vale troubleshooting to copilot-instructions.md
- Add shell command permissions to settings.json

Reduces Vale warnings from 794 to 187 (76% reduction) while keeping
useful style validation active.
@jstirnaman jstirnaman force-pushed the claude/phase2-vale-improvements-cMYcc branch from 7d5898d to 43fe85c Compare February 6, 2026 18:07
@jstirnaman jstirnaman marked this pull request as ready for review February 6, 2026 18:11
@jstirnaman jstirnaman requested a review from a team as a code owner February 6, 2026 18:11
@jstirnaman jstirnaman requested review from sanderson and removed request for a team February 6, 2026 18:11
@jstirnaman jstirnaman changed the title fix(vale): exclude URLs and shortcode attributes from spell checking fix(vale): update (vale sync), improve rules, exclude URLs and shortcode attributes from spell checking Feb 6, 2026
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates the repository’s Vale configuration and rule set to reduce false positives (URLs, paths, Hugo shortcodes, code spans) and adds supporting internal documentation so Vale can be enabled in PR/CI checks with less noise.

Changes:

  • Updated .vale.ini to adjust enabled/disabled rules and add global TokenIgnores for URLs/paths/inline code.
  • Enhanced/customized Vale styles (InfluxDataDocs + synced Google/write-good changes), including a new InfluxDataDocs.Units rule and expanded spelling ignores.
  • Added internal “vale-linting” workflow documentation and referenced it from existing Copilot/Claude guidance.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file
File Description
.vale.ini Adds global ignore patterns and disables select rules (Google.Units, Vale.Terms, write-good.TooWordy).
.github/copilot-instructions.md Updates troubleshooting table and links to the new vale-linting skill doc.
.claude/skills/vale-linting/SKILL.md New comprehensive Vale workflow/how-to document.
.claude/skills/content-editing/SKILL.md Adds a Vale “Style Linting” step and command examples.
.claude/settings.json Expands allowed shell commands (including Vale wrapper and related tooling).
.claude/agents/ci-automation-engineer.md Improves formatting and adds explicit Vale expertise responsibilities.
.ci/vale/styles/InfluxDataDocs/Units.yml Introduces custom units rule to allow InfluxDB duration literals while checking byte units.
.ci/vale/styles/InfluxDataDocs/Terms/ignore.txt Expands spelling ignore list with additional technical terms.
.ci/vale/styles/InfluxDataDocs/Spelling.yml Excludes code/raw/table scopes and adds filters for URLs and shortcode attributes.
.ci/vale/styles/InfluxDataDocs/Capitalization.yml Expands heading capitalization exceptions (products/acronyms/etc.).
.ci/vale/styles/Google/Units.yml Synced Google units token patterns (note: Google.Units is disabled in .vale.ini).
.ci/vale/styles/Google/Quotes.yml Raises severity to error and adjusts message text.
.ci/vale/styles/Google/Ordinal.yml Removes ordinal exceptions (more strict checking).
.ci/vale/styles/Google/Colons.yml Updates regex pattern for colon capitalization detection.
.ci/vale/styles/Google/AMPM.yml Tightens AM/PM regex with word boundaries.
.ci/vale/styles/.vale-config/2-Hugo.ini Adds Hugo-specific ignores for shortcodes/link constructs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants