Initial commit

2026-08-10 21:37:46 -07:00
commit 56e75d9cde
@@ -0,0 +1,65 @@
+# Contributing
+
+## Before opening an issue
+
+Run `solixauto doctor` and include its output. It reports platform, Python
+version, dependencies, whether credentials resolve, detected subnets, and
+notification status.
+
+**Do not paste secrets.** Never include:
+
+- `notifications.yaml` or any part of it
+- your `.env` file, Anker email, or password
+- your ntfy topic (anyone with it can read your alerts)
+
+Device profiles contain serial numbers. Redact them if that matters to you.
+
+## Reporting a device that does not work
+
+Include:
+
+- model and part number, e.g. `A1782`
+- what `solixauto discover-anker` printed
+- whether the device shows as online in the Anker app at the time
+- for Shelly devices, generation and model, plus `solixauto conflicts <plug>`
+
+Devices that pair over Bluetooth only cannot be supported here. They publish
+nothing to Anker's cloud MQTT broker. That is a hardware limitation, not a bug.
+
+## Field mappings
+
+Telemetry field names come from the upstream
+[anker-solix-api](https://github.com/thomluther/anker-solix-api) project.
+Corrections to field meanings belong there, not here.
+
+If a field is wrong or missing for your model, that is the right place to
+report it. This project only adds derived fields computed from what upstream
+already decodes.
+
+## Code changes
+
+- No comments in code; the project is written without them
+- Match the existing style rather than introducing a formatter
+- Anything touching the engine needs a matching check in `--test` output. If
+  a behaviour cannot be observed with `--test`, it is very hard for a user to
+  trust it.
+- Safety-relevant changes (the battery floor, stale handling, rate limits)
+  should come with a description of the failure mode they address
+
+## Testing
+
+There is no unit test suite yet. Contributions that add one are welcome.
+
+At minimum, exercise the paths you touched:
+
+```bash
+solixauto run <profile> --test --offline
+solixauto run <profile> --test --simulate battery_soc=12
+solixauto run <profile> --dry-run --cycles 6
+```
+
+A fake Shelly is easy to stand up with aiohttp if you need to test the control
+path without hardware; the RPC surface used is small: `/shelly`,
+`/rpc/Shelly.GetStatus`, `/rpc/Shelly.GetConfig`, `/rpc/Switch.Set`,
+`/rpc/Switch.SetConfig`, `/rpc/Schedule.List`, `/rpc/Schedule.Delete`,
+`/rpc/Webhook.List`.