esp-matter/DEVELOPER_GUIDE.md

Developer Guide

This guide covers the development workflow and tooling for contributors to esp-matter.

Pre-commit Hooks

The repository uses pre-commit to run automated checks before each commit. Following hooks are configured:

1. astyle_py — C/C++ Code Formatter

   astyle_py enforces consistent C/C++ formatting. The formatting rules are defined in tools/ci/astyle-rules.yml.

2. keep-sorted — Sorted Block Enforcer

   keep-sorted is used in documentation and source files to maintain alphabetical ordering of lists and sections.

3. codespell — Spell Checker

   codespell catches common misspellings in source code, documentation, and comments. Configuration is in .codespellrc.

Setup

1. Install pre-commit

python3 -m pip install pre-commit

2. Install the hooks

From the repository root:

cd $ESP_MATTER_PATH
pre-commit install

This registers the hooks so they run automatically on git commit.

Usage

Once installed, the hooks run on every git commit against the staged files. If a hook reformats a file, the commit is aborted — review the changes, git add the updated files, and commit again.

Running locally

Run all hooks on every file in the repository:

pre-commit run --all-files

Run all hooks only on staged files (same as what happens on commit):

pre-commit run

Run a specific hook:

pre-commit run astyle_py --all-files
pre-commit run keep-sorted --all-files
pre-commit run codespell --all-files

Run hooks on specific files:

pre-commit run --files path/to/file.cpp path/to/other_file.h

Skip hooks for a one-off commit (not recommended):

git commit --no-verify