docs: add CLAUDE.md orientation file and pr-workflow skill#1672
Merged
Conversation
Adds a structured CLAUDE.md for LLM contributors covering what the project is, code style (terse docstrings, comment discipline, ruff settings), Conventional Commits + PR conventions, how to run tests, Cython build conventions and .pxd discipline, a useful-entry-points table, and a short 'things not to do' list. Adds a pr-workflow skill under .claude/skills/pr-workflow/SKILL.md that summarises the parts that matter at PR-creation time: branch from origin/master, no PR template (free-form body), Conventional Commits prefix is enforced by commitlint + commitizen, .pxd discipline for any module in TO_CYTHONIZE, pass the body via --body-file so Markdown isn't shell-escaped. No runtime code changes; this commit only adds contributor-facing documentation under CLAUDE.md and .claude/.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #1672 +/- ##
=======================================
Coverage 99.76% 99.76%
=======================================
Files 33 33
Lines 3401 3401
Branches 461 461
=======================================
Hits 3393 3393
Misses 5 5
Partials 3 3 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a structured
CLAUDE.mdorientation file for LLM contributors,and a
pr-workflowskill under.claude/skills/pr-workflow/SKILL.mdthat walks through this repo's PR conventions. Shaped after the same
pair landed in
esphome/aioesphomeapi#1646, adapted for this repo.Details
The
CLAUDE.mdcovers:Cython on hot paths, pure-Python fallback supported).
ruff config (
line-length = 110,target-version = "py39",isort
profile = "black").commitlint + commitizen pre-commit, imperative subject, no
Co-Authored-Bytrailers from automated agents.poetry run pytest --durations=20 --timeout=60 -v tests/
make test), with notes on CodSpeed benchmarks and the CI matrix(CPython 3.9–3.14, 3.14t free-threaded, PyPy 3.9 / 3.10).
TO_CYTHONIZEinbuild_ext.py,.pxddiscipline,
SKIP_CYTHON/REQUIRE_CYTHONenv vars,BuildExt's exception-swallowing pure-Python fallback._core.py,_cache.py,_dns.py,_protocol/{incoming,outgoing}.py,_handlers/*,_services/*,_utils/*,const.py,asyncio.py, etc..c,don't change
cdefsignatures without updating the.pxd, don'ttighten timing constants without an RFC citation, don't break the
3.14t free-threaded entry).
The
pr-workflowskill summarises the parts that matter at PR-creationtime — branch from
origin/master(this repo usesmaster, notmain,and there is no fork in the maintainer workflow), no PR template so
the body is free-form (with a suggested Summary / Details / Test plan
shape), Conventional Commits prefix is mandatory,
.pxddisciplinefor any module in
TO_CYTHONIZE, pass the body via--body-filesoMarkdown backticks aren't shell-escaped, and which CI jobs gate the PR.
No runtime code changes; this PR only adds contributor-facing
documentation under
CLAUDE.mdand.claude/.Test plan
pre-commit run --files CLAUDE.md .claude/skills/pr-workflow/SKILL.mdpasses (prettier reformatted the Markdown on the first run; the
committed version is prettier-clean).
docs: ...) is Conventional-Commits compliantand will pass the
commitlintCI job.no-op for this PR beyond confirming the lint + commitlint jobs
go green.