|
| 1 | +# Contributing to ebus-sdk |
| 2 | + |
| 3 | +Thanks for your interest in contributing! `ebus-sdk` is the Python SDK for the [Electrification Bus (eBus)](https://ebus.energy) integration framework, which adopts and supports the [Homie Convention](https://homieiot.github.io). The SDK provides device-role and controller-role implementations, property abstractions, and an MQTT transport layer (delegated to [`ebus-mqtt-client`](https://github.com/electrification-bus/ebus-mqtt-client)). |
| 4 | + |
| 5 | +## How to contribute |
| 6 | + |
| 7 | +### Discussions |
| 8 | + |
| 9 | +Use [Discussions](https://github.com/electrification-bus/python-sdk/discussions) for: |
| 10 | + |
| 11 | +- Open-ended questions about the SDK's design, API shape, or intent ("how should I model X as a Homie node?") |
| 12 | +- Integration questions ("I'm trying to use this with broker Y / device Z, what's the recommended pattern?") |
| 13 | +- Proposed new abstractions, callback shapes, or convenience helpers — worth aligning on the API before writing the code |
| 14 | +- Questions about the relationship between the SDK and the [Electrification Bus specification](https://github.com/electrification-bus/specification) (the SDK aims to be a faithful implementation of the spec; spec-level questions belong in the spec repo's Discussions) |
| 15 | +- Thinking out loud about a proposed change before scoping it |
| 16 | + |
| 17 | +Discussions are open-ended — a good place to align on direction before something becomes a concrete change. Aligned outcomes often turn into one or more Issues or pull requests. |
| 18 | + |
| 19 | +### Issues |
| 20 | + |
| 21 | +Use [Issues](https://github.com/electrification-bus/python-sdk/issues) for actionable changes: |
| 22 | + |
| 23 | +- Bug reports with reproduction steps (broker, paho version, code snippet) |
| 24 | +- Spec-conformance gaps where the SDK diverges from the [Electrification Bus specification](https://github.com/electrification-bus/specification) (note which spec document and section) |
| 25 | +- Concrete feature requests with a clear scope and a use case |
| 26 | +- Documentation gaps where a specific README, example, or docstring change is intended |
| 27 | +- Discussion outcomes that have alignment and a clear scope |
| 28 | + |
| 29 | +If you're not sure whether something is an Issue or a Discussion, start with a Discussion — we can convert it later. |
| 30 | + |
| 31 | +### Pull requests |
| 32 | + |
| 33 | +Pull requests are welcome. |
| 34 | + |
| 35 | +- For small fixes (typos, docstring tweaks, version bumps, low-risk bug fixes with a test), open a PR directly. |
| 36 | +- For substantive changes (new public API surface, changes to existing API shapes, new dependencies, changes that alter device-lifecycle / discovery / property semantics), open a Discussion or Issue first so we can align on scope before you invest the effort. |
| 37 | +- **Spec conformance is the north star.** The SDK exists to implement the [Electrification Bus specification](https://github.com/electrification-bus/specification). When a PR's behavior is normative (device states, property contracts, topic structure), point to the spec section it implements. If the spec is ambiguous or wrong, file an Issue against the spec repo first and reference it from the PR here. |
| 38 | +- **MQTT-only changes belong elsewhere.** Pure transport concerns (TLS, mTLS, paho upgrades, reconnection tuning, broker auth) belong in [`ebus-mqtt-client`](https://github.com/electrification-bus/ebus-mqtt-client), not here. This SDK is the Homie/eBus layer on top — keep that boundary clean. |
| 39 | +- **Lint before sending.** The repo enforces [ruff](https://github.com/astral-sh/ruff) via the [`lint`](.github/workflows/lint.yml) workflow — run `ruff check` and `ruff format` locally before pushing. CI will catch what you miss, but green-first is friendlier. |
| 40 | +- **Tests are required.** New behavior needs a test (`pytest tests/`); new bug fixes need a regression test. Match the existing pattern (mocked paho via `ebus-mqtt-client`'s test scaffolding) unless the change genuinely requires a real broker — in which case open a Discussion first. |
| 41 | +- **Keep comments to a minimum.** The project style is to write self-explanatory code and reserve comments for non-obvious *why* (a spec quirk, a Homie nuance, a workaround for a specific paho behavior). Don't add comments that just restate the code. |
| 42 | +- **Version bumps touch two files.** When a release-worthy change lands, bump `version` in both `pyproject.toml` and `setup.py` (the `setup.py` shim exists so legacy `setuptools<61` — pinned in Yocto kirkstone — can build a wheel with correct metadata; the docstring at the top of `setup.py` explains this). |
| 43 | +- One commit per logical change is fine; we don't require squash or any particular branch naming. |
| 44 | + |
| 45 | +## Releases |
| 46 | + |
| 47 | +Releases to PyPI are automated via the [`Publish to PyPI`](.github/workflows/publish.yml) GitHub Actions workflow, which runs on `v*` git tags using PyPI [trusted publishing](https://docs.pypi.org/trusted-publishers/). Contributors don't need to do anything special — once a maintainer tags `vX.Y.Z`, the workflow tests and publishes. |
| 48 | + |
| 49 | +## Code of conduct |
| 50 | + |
| 51 | +Be respectful and constructive. We appreciate everyone who takes the time to file an issue, start a discussion, or send a pull request. |
| 52 | + |
| 53 | +## Maintenance posture |
| 54 | + |
| 55 | +`ebus-sdk` is an active alpha library. Updates and maintenance, including responses to issues filed on GitHub, will take place on an "as time and resources permit" basis. The SDK is maintained alongside [`ebus-mqtt-client`](https://github.com/electrification-bus/ebus-mqtt-client) and the [Electrification Bus specification](https://github.com/electrification-bus/specification) — see the specification repo's README §Governance for the project's long-term governance context. |
0 commit comments