Best practices for configuring code quality automation in Freerouting. Covers pre-commit hooks, linter configuration (codespell, yamllint, shellcheck, Spotless), and GitHub Actions integration. Use when maintaining or debugging code quality checks, when adding new pre-commit hooks, or when CI quality gates fail unexpectedly. Triggers on: pre-commit, codespell, yamllint, GitHub Actions, quality gates, CI failures.
Best practices for configuring code quality automation in Freerouting. Covers pre-commit hooks, linter configuration (codespell, yamllint, shellcheck, Spotless), and GitHub Actions integration. Use when maintaining or debugging code quality checks, when adding new pre-commit hooks, or when CI quality gates fail unexpectedly. Triggers on: pre-commit, codespell, yamllint, GitHub Actions, quality gates, CI failures.
This skill documents best practices for configuring and maintaining code quality automation in the Freerouting project. It covers pre-commit hooks, linter configuration patterns, and GitHub Actions integration for consistent code quality enforcement.
2. Core Principles
2.1 Centralize Tool Configuration
Best Practice: Concentrate configuration for each tool in its canonical configuration file rather than scattering settings across multiple locations.
codespell: Use pyproject.toml ([tool.codespell]) as the single source of truth
yamllint: Use .yamllint.yaml for all YAML linting rules
shellcheck: Use .shellcheckrc or inline args in pre-commit config
Spotless: Use build.gradle for Java formatting rules
Benefits:
Single location to update settings
Consistent behavior between CLI and pre-commit execution
Easier maintenance and auditing
Avoids configuration drift between environments
2.2 Pre-commit Hook Pattern
Best Practice: For file-filtering tools (codespell, yamllint, shellcheck), use the exclude field in pre-commit hook configuration rather than passing exclusion arguments to the underlying tool.
This approach is more efficient because:
Pre-commit filters files before invoking the tool
Reduces the workload on each hook
Keeps hook definitions self-contained and readable
Works consistently across all hook types
Example Pattern:
-repo:https://github.com/owner/toolrev:vX.Y.Zhooks:-id:tool-idexclude:^(excluded_dir/|excluded_files\.ext$|pattern_to_skip)# Tool-specific args go here (non-filtering only)
-name:Runpre-commithooksenv:RAW_LOG:pre-commit.logCS_XML:pre-commit.xmlrun:|
set -o pipefail
pre-commit run --show-diff-on-failure --color=always --all-files | tee ${RAW_LOG}
-name:ConvertRawLogtoCheckstyleformat(launchaction)uses:mdeweerd/logToCheckStyle@v2025.1.1if:${{failure()}}with:in:${{env.RAW_LOG}}
