Repository navigation
Contributing
Contributions are welcome! Whether you're fixing a bug, adding a feature, or improving documentation, this page will guide you through the development workflow.
Be respectful and constructive. All contributions must be made in good faith.
- Python 3.13+
-
tox (
pip install tox) - A clone of this repository
git clone https://github.com/firstof9/openevse.git
cd openevse
# Install tox environments
tox -e py313 --notest- Fork the repository on GitHub.
- Create a feature branch from
main:git checkout -b feature/my-new-feature
- Core integration code lives in
custom_components/openevse/. - Tests live in
tests/. - If adding a new entity, read the
add-entity-platformskill for the established patterns. - Always place imports at the top of the module (not inside functions) — this is enforced by the
PLC0415lint rule.
tox -e py313All tests must pass before submitting a PR.
.tox/py313/bin/prek run --all-files --show-diff-on-failureThis runs:
- ruff — linting
- ruff-format — code formatting
- mypy — static type checking
- codespell — spell checking
Fix all reported issues before submitting.
- If you added or changed features, update
README.md. - If the change is significant, update or add relevant wiki pages.
- Open a PR against the
mainbranch. - Fill in the PR template completely.
- Reference any related issues with
Fixes #<issue_number>.
If you need to test changes to the upstream python-openevse-http library alongside the integration:
- Edit
requirements.txt:-e /path/to/your/cloned/python-openevse-http
- Recreate the tox environment:
tox -e py313 --recreate
Caution
Always revert requirements.txt back to the published version (e.g., python-openevse-http==0.4.0) before committing or pushing. Never ship a local path reference.
Follow the custom-service-definition skill which covers:
- Defining the service schema in
services.yaml - Registering the handler in
services.py - Adding service name constants to
const.py - Writing corresponding tests
| Tool | Purpose |
|---|---|
ruff |
Linting (PEP8, import order, etc.) |
ruff-format |
Code formatting (replaces black) |
mypy |
Static type checking |
codespell |
Spell checking in code & comments |
Key style rules:
- All imports must be at the module top-level (no inline imports inside functions).
- Use type hints throughout.
- Use
Finalfor constants inconst.py. - Warning message templates should use the shared constants
FW_VERSION_WARNandNON_NUMERIC_WARNfromconst.py.
Open a bug report at: https://github.com/firstof9/openevse/issues/new/choose
A great bug report includes:
- Steps to reproduce
- Expected vs. actual behavior
- HA version, integration version, firmware version
- Relevant Home Assistant logs
- Diagnostics download (if applicable)
By contributing, you agree that your contributions will be licensed under the MIT License.