diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f6b7e2cda..d606bbeae 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -5,4 +5,13 @@ repos: - id: astyle_py args: ['--astyle-version=3.4.7', '--rules=tools/ci/astyle-rules.yml'] +- repo: https://github.com/google/keep-sorted + rev: v0.7.1 + hooks: + - id: keep-sorted +- repo: https://github.com/codespell-project/codespell + rev: v2.4.1 + hooks: + - id: codespell + args: ['--config=.codespellrc', '--write-changes'] diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md new file mode 100644 index 000000000..6a98b24f4 --- /dev/null +++ b/DEVELOPER_GUIDE.md @@ -0,0 +1,80 @@ +# Developer Guide + +This guide covers the development workflow and tooling for contributors to esp-matter. + +## Pre-commit Hooks + +The repository uses [pre-commit](https://pre-commit.com/) to run automated checks before each commit. Following hooks are configured: + +1. astyle_py — C/C++ Code Formatter + + [astyle_py](https://github.com/espressif/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](https://github.com/google/keep-sorted) is used in documentation and + source files to maintain alphabetical ordering of lists and sections. + +3. codespell — Spell Checker + + [codespell](https://github.com/codespell-project/codespell) catches common + misspellings in source code, documentation, and comments. + Configuration is in `.codespellrc`. + +### Setup + +1. Install pre-commit + +```bash +python3 -m pip install pre-commit +``` + +2. Install the hooks + +From the repository root: + +```bash +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: + +```bash +pre-commit run --all-files +``` + +Run all hooks only on staged files (same as what happens on commit): + +```bash +pre-commit run +``` + +Run a specific hook: + +```bash +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: + +```bash +pre-commit run --files path/to/file.cpp path/to/other_file.h +``` + +Skip hooks for a one-off commit (not recommended): + +```bash +git commit --no-verify +```