[Documentation] Expand .coderabbit.yml with WP-docs improvements and revalidate

[ashleyshaw]

---

title: "Expand .coderabbit.yml with WP-docs improvements and revalidate"
type: "Documentation"
labels:

• "documentation"
• "automation"
• "governance"
  assignees:
• "ashleyshaw"
  template: "19-documentation.md"

---

Summary

Expand the root .coderabbit.yml with the useful improvements already proven in the WP-docs repository, align it with the current CodeRabbit YAML schema and configuration reference, and revalidate it with the existing validation script.

This should produce a more useful, lower-noise, and better-scoped CodeRabbit setup for lightspeedwp/.github, with configuration that is explicit, schema-valid, maintainable, and suitable for a repository focused on GitHub automation, governance, documentation, and shared standards. CodeRabbit requires the repository YAML file to live at the repo root, and the configuration present on the branch under review is the one used for that review. (docs.coderabbit.ai)

Problem

The current .coderabbit.yml is valid, but it does not yet fully reflect the configuration options and structure now available in CodeRabbit’s documented YAML schema and reference. In particular, this repository still needs a clearer, more deliberate brief for:

• root-level schema usage and validation,
• supported language configuration,
• inheritance behaviour,
• review behaviour and automation settings,
• path filtering and path-specific review instructions,
• repo-specific guidance for workflows, scripts, markdown, changelog, and governance files.

This repo is not a typical application repo. Because lightspeedwp/.github mainly contains GitHub workflows, repo standards, docs, templates, and automation-related files, the CodeRabbit config should be tuned for governance, safety, clarity, and maintainability rather than generic code-review defaults. CodeRabbit’s configuration reference explicitly supports root settings such as language, review settings, chat settings, path instructions, and reviewer automation, which makes a repo-specific configuration worthwhile here. (docs.coderabbit.ai)

Why this matters

A better .coderabbit.yml should improve review quality without adding maintenance drag. The objective is not to configure every possible option; it is to define a clear baseline that gives CodeRabbit enough context to review the right files in the right way, while avoiding noisy or low-value comments.

For this repository, the biggest ROI comes from:

• clearer review behaviour,
• better scoping through filters and path instructions,
• explicit inheritance so central/shared defaults can be merged intentionally,
• schema-backed validation to keep the file correct and editor-friendly.

CodeRabbit documents that inheritance is disabled by default and must be explicitly enabled with inheritance: true; when enabled, config is merged up the hierarchy rather than only using the highest-priority source. (docs.coderabbit.ai)

Goal

Bring .coderabbit.yml in lightspeedwp/.github up to a stronger baseline by:

• carrying across the relevant improvements from WP-docs,
• aligning the file to the current CodeRabbit schema and supported configuration keys,
• improving path-based review guidance for this repo’s actual contents,
• keeping the config minimal, modular, and maintainable,
• validating the final YAML cleanly.

Schema and YAML requirements

Root file and schema declaration

The configuration must remain a root-level .coderabbit.yml or .coderabbit.yaml, and it should include the YAML language server schema header so editors can validate the file against CodeRabbit’s schema. CodeRabbit’s YAML docs show the schema comment format and note that the file must be located in the repository root. (docs.coderabbit.ai)

Expected schema header:

# yaml-language-server: $schema=https://docs.coderabbit.ai/schema/schema.v2.json

If the repository continues to use the older schema URL currently shown in some CodeRabbit examples, that should be reconciled intentionally rather than left inconsistent. The issue work should confirm which schema URL the repo validator expects and keep the config aligned with that choice. CodeRabbit’s docs show schema-backed YAML support, and the validator docs confirm the config is intended to be validated and debugged as YAML. (docs.coderabbit.ai)

Language setting

If language is configured, it should use a supported CodeRabbit locale. The configuration reference lists supported values, including en-GB, while the current issue body mentions en-uk, which does not appear in the published allowed list. If language is kept, it should be corrected to a supported value such as en-GB. (docs.coderabbit.ai)

Inheritance

The config should explicitly declare:

inheritance: true

CodeRabbit states that inheritance is off by default and must be enabled at the root. With inheritance enabled, parent configuration levels are merged, the chain continues while parent configs also opt in, and merge behaviour differs by type: objects merge, arrays are combined, and scalar child values override parent values. This matters for a repo like .github, where some settings may eventually be shared centrally while others remain repo-specific. (docs.coderabbit.ai)

Configuration areas to improve

P1 — High priority

These are the most important improvements and should be tackled first.

1. Correct and harden the root configuration

• Confirm the correct root filename and keep it as the single source of truth
• Add or confirm the schema header
• Replace unsupported language: 'en-uk' with a supported locale if language is kept
• Confirm or add inheritance: true
• Keep the file structured in clear sections so future maintenance is straightforward

2. Review behaviour

Review behaviour is the highest-value area for this repo. The issue should explicitly review and document which of the following CodeRabbit options are appropriate:

• reviews.profile
• reviews.high_level_summary
• reviews.review_status
• reviews.review_details
• reviews.request_changes_workflow
• reviews.auto_review.enabled
• reviews.auto_review.drafts

These are shown in CodeRabbit’s YAML examples and configuration reference as supported review controls. The task here is not to enable them all blindly, but to choose defaults that improve signal without adding clutter. (docs.coderabbit.ai)

3. Path instructions for repo-critical areas

Use path_instructions to give CodeRabbit focused review guidance for the highest-value paths in this repository. CodeRabbit documents path instructions as a way to scope review guidance to specific files or directories. (docs.coderabbit.ai)

At minimum, assess and define instructions for:

• .github/workflows/**
• shell scripts and automation files
• JavaScript helper scripts if present
• Python helper scripts if present
• markdown files
• README.md
• changelog / release-note files
• issue templates / PR templates / repo meta files

For this repo, those instructions should prioritise:

• least-privilege GitHub Actions permissions,
• secret handling and token safety,
• action pinning and workflow maintainability,
• accurate and concise documentation,
• avoiding unnecessary automation complexity,
• governance clarity over stylistic nitpicks.

4. Path filtering

Review and tighten path exclusions so CodeRabbit does not waste review effort on low-signal artefacts.

• Expand path_filters or equivalent path exclusion config if supported by the active schema
• Exclude generated, cached, vendor, and other non-reviewable artefacts where appropriate
• Avoid excluding files that still need security or governance review

This should be conservative: enough to reduce noise, but not so broad that important configuration changes are ignored.

5. Validation

• Run validate-coderabbit-yml.cjs
• Confirm .coderabbit.yml validates successfully
• Record whether validation used remote schema or local fallback
• Resolve any schema mismatch or unsupported keys before merge

CodeRabbit also provides a YAML validator in its docs, reinforcing that schema validation is a first-class part of the config workflow. (docs.coderabbit.ai)

P2 — Medium priority

These are useful improvements if they are supported by the current schema and prove valuable for this specific repo.

6. Chat behaviour

The current issue body mentions chat.auto_reply: true. The configuration reference lists auto-reply support and indicates it defaults to enabled. This should be reviewed explicitly rather than retained by habit. If kept, the reason should be documented. (docs.coderabbit.ai)

• Confirm whether chat.auto_reply should remain enabled
• Check whether any other chat-related settings are relevant to a public/shared standards repo
• Avoid enabling chat features that add maintenance cost without clear benefit

7. Auto-labelling and reviewer assignment

If the schema supports the currently used keys in this repo, review and refine them based on practical usefulness.

• Review auto_labels path-based rules for docs, CI, shell, test, JS, and Python
• Review auto_assign logic for reviewer routing
• Keep both systems simple, predictable, and low-maintenance
• Remove labels or assignment rules that are too broad, noisy, or repo-specific to WP-docs

8. Modular review guidance by file type

The WP-docs-derived improvements mention more granular instructions by file type. That is likely useful here if the guidance is concise and repo-appropriate.

Assess whether the config should include focused instructions for:

• shell scripts
• JavaScript files
• Python files
• bats tests
• workflow YAML
• markdown/docs
• changelog / release documentation

The aim is to make reviews more context-aware, not to duplicate existing linting or CI checks.

P3 — Lower priority / follow-up

These are worth considering after the core configuration is stable.

9. Inheritance strategy documentation

Because CodeRabbit’s inheritance model supports multi-level merging across repository YAML, central YAML, UI settings, and defaults, this repo should document whether it is:

• primarily a consumer of central/shared config,
• expected to define repo-only overrides,
• or intended to become part of a broader organisation-wide configuration pattern.

CodeRabbit documents different hierarchy levels for SaaS/cloud and self-hosted deployments, and notes that without inheritance only the highest-priority source is used. (docs.coderabbit.ai)

10. Future centralisation

CodeRabbit recommends central configuration and inheritance for managing config across multiple repositories, rather than relying on shared remote config. If LightspeedWP intends to standardise CodeRabbit behaviour across repositories, this issue should leave the .github config in a state that can participate cleanly in that model later. (docs.coderabbit.ai)

11. Remote schema fetch reliability

The current issue notes that validation passed with a local schema fallback due to a fetch error. This should be tracked as follow-up work if it cannot be fixed inside this issue.

• identify why remote schema fetch failed,
• confirm whether the validator should use the published schema URL directly,
• ensure future validation is reproducible for maintainers.

Proposed workflow

Phase 1 — assess current configuration

• Inspect the existing .coderabbit.yml
• Compare it with the WP-docs version
• Cross-check every non-trivial key against the CodeRabbit configuration reference
• Identify any keys or values that are unsupported, outdated, or not suitable for .github

Phase 2 — update the file

• Correct schema and root-level settings
• Add or refine inheritance
• Review and tune review behaviour
• Improve path filters
• Add or refine path instructions for high-value repo areas
• Review chat, labels, and reviewer automation where useful

Phase 3 — validate and trim

• Run the repo validation script
• Resolve unsupported keys or value mismatches
• Remove redundant or noisy instructions
• Keep only the parts that clearly improve review signal

Phase 4 — document intent

• Record why the chosen settings were kept
• Note any settings intentionally left out
• Clarify how inheritance is expected to work for this repo going forward

Acceptance criteria

• .coderabbit.yml is aligned with the current CodeRabbit schema and configuration reference
• The file includes an explicit schema declaration suitable for editor validation
• Any configured language value uses a supported locale
• inheritance: true is set intentionally
• Review behaviour is tuned for practical, low-noise feedback
• Path instructions exist for the most important repo areas
• Path filtering reduces low-value review noise without hiding important changes
• The final YAML validates successfully with the repo’s validation script
• The configuration remains small enough to maintain comfortably

Notes for implementation

• Prefer small, modular changes over a large one-shot expansion
• Do not introduce settings just because they exist in the schema
• Do not duplicate existing linting, CI, or repo governance unnecessarily
• Prioritise options that materially improve review quality for workflows, docs, automation, and shared repo standards
• Use the published CodeRabbit configuration reference as the source of truth for supported keys and values

References

• CodeRabbit YAML configuration guide
• CodeRabbit schema v2
• CodeRabbit configuration reference
• CodeRabbit configuration inheritance
• CodeRabbit YAML validator