Skip to content

Contributing

firstof9 edited this page Sep 28, 2026 · 1 revision

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.


Code of Conduct

Be respectful and constructive. All contributions must be made in good faith.


Getting Started

Prerequisites

  • Python 3.13+
  • tox (pip install tox)
  • A clone of this repository

Setup

git clone https://github.com/firstof9/openevse.git
cd openevse

# Install tox environments
tox -e py313 --notest

Development Workflow

1. Fork & Branch

  1. Fork the repository on GitHub.
  2. Create a feature branch from main:
    git checkout -b feature/my-new-feature

2. Make Your Changes

  • Core integration code lives in custom_components/openevse/.
  • Tests live in tests/.
  • If adding a new entity, read the add-entity-platform skill for the established patterns.
  • Always place imports at the top of the module (not inside functions) — this is enforced by the PLC0415 lint rule.

3. Run Tests

tox -e py313

All tests must pass before submitting a PR.

4. Run Linting & Formatting

.tox/py313/bin/prek run --all-files --show-diff-on-failure

This runs:

  • ruff — linting
  • ruff-format — code formatting
  • mypy — static type checking
  • codespell — spell checking

Fix all reported issues before submitting.

5. Update Documentation

  • If you added or changed features, update README.md.
  • If the change is significant, update or add relevant wiki pages.

6. Submit a Pull Request

  • Open a PR against the main branch.
  • Fill in the PR template completely.
  • Reference any related issues with Fixes #<issue_number>.

Testing Against Local Library Changes

If you need to test changes to the upstream python-openevse-http library alongside the integration:

  1. Edit requirements.txt:
    -e /path/to/your/cloned/python-openevse-http
  2. 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.


Adding New Services

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

Code Style

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 Final for constants in const.py.
  • Warning message templates should use the shared constants FW_VERSION_WARN and NON_NUMERIC_WARN from const.py.

Reporting Bugs

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)

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Clone this wiki locally