Contributing

Contributing

Thanks for helping. The most valuable contribution right now is a compatibility report. You don't need to write any code.

The official rules are in CONTRIBUTING.md. This page is a friendly summary.

Ways to help

• Report your meter, working or not (how)
• Add your council to the "reported working" list (pull request to Tested hardware and Is my area covered?)
• Improve this wiki: fix unclear steps, add photos (IDs blurred)
• Fix bugs in the receiver or card
• Test the card in different themes, phone widths and languages

Scope: what fits and what doesn't

Welcome	Not accepted
Better reception of supported Taggle meters	Decrypting or key-searching encrypted meters
Home Assistant integration improvements	Council portal scraping or logins
Card improvements	Unrelated radio decoders
Docs, tests, synthetic test data	Real meter IDs, recordings, captures or private logs

Development setup

You'll need Python 3.11–3.13 and Node.js (for the card tests).

git clone https://github.com/Spicynostalgia/ha-taggle.git
cd ha-taggle
python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'

Before you submit

ruff check .
pytest -q
node --test tests/card.test.cjs
python scripts/check_release.py

All four must pass.

• Card changes: edit card/taggle-card.js, then copy it to dist/taggle-card.js. The two must be identical. Test light and dark themes, narrow widths, missing or renamed entities, and keyboard access.
• Test data: generate fake signals with tests/synthetic.py. Never commit real frames or IDs.
• Containers: build docker/Dockerfile (from the repo root) and addon/Dockerfile (from addon/).
• Screenshots: CHROME=/path/to/chromium python3 scripts/screenshots.py regenerates the card images from fictional data.

Pull requests

Explain what changed, any compatibility effects, and how you tested it. Contributions are under the project's MIT licence.

Editing this wiki

The wiki is a set of Markdown files. Page names use hyphens (Getting-Started.md). Link pages with [Getting started](Getting-Started). Use fictional IDs like 123456 everywhere. GitHub explains how wikis work and the callout syntax (> [!TIP]) used here.

Technical detail: screenshots and test coverage

Regenerate the synthetic README/card previews with Python's standard library and an installed Chromium:

CHROME=/absolute/path/to/chromium python3 scripts/screenshots.py

The script serves the repository over loopback HTTP and writes four 2× PNGs into docs/images/. The screenshot harness accepts theme=light|dark, width=NNN (card width in CSS pixels), and scenario=calibrated|raw|multi. It fixes the clock and uses only fictional IDs and synthetic 48-hour history, including missing and zero-use hours. Preview through an HTTP server, not file://. Use the same Chromium version and fonts for repeatable pixels; inspect and commit the generated PNGs. Label synthetic previews separately from real hardware screenshots.

Tests generate fake frames and filtered PN-modulated IQ from the project's own encoder: no captures, real frames or private analysis artifacts are included. CI tests Python 3.11/3.13 and builds both container variants for amd64/aarch64 without pushing images. See CONTRIBUTING.md, CHANGELOG.md and RELEASE-CHECK.md.

Publishing

Forking? This checkout is already configured for spicynostalgia. In a fork:

1. Change the add-on image in addon/config.yaml to ghcr.io/<your-lowercase-owner>/ha-taggle-addon-{arch}.
2. Change the standalone image in docker-compose.yml to ghcr.io/<your-lowercase-owner>/ha-taggle:latest.
3. Review repository URLs and verify the image paths before tagging, then commit the changes.

Keep {arch} literal: Home Assistant substitutes amd64 or aarch64, and uses the add-on version as the image tag. set_owner.py replaces only remaining GITHUB_OWNER placeholders; it does not retarget image names already containing spicynostalgia.

Keep addon/config.yaml, root pyproject.toml and addon/pyproject.toml versions equal, and add the matching ## <version> section to CHANGELOG.md (also update addon/CHANGELOG.md). A pushed tag such as v0.3.0 triggers release.yml; it rejects version mismatches or missing release notes before publishing. You can validate locally with:

python scripts/prepare_release.py v0.3.0 --notes /tmp/taggle-release-notes.md

The workflow uses only the built-in GITHUB_TOKEN, with packages: write and contents: write. It publishes ghcr.io/<owner>/ha-taggle-addon-amd64:<version> and ha-taggle-addon-aarch64:<version>, plus the standalone ghcr.io/<owner>/ha-taggle:<version> and :latest manifest for linux/amd64 and linux/arm64 using Buildx/QEMU. Tags omit the leading v. After all images succeed, it creates a GitHub Release using that version's changelog section.

After the first publication, make all three GHCR packages public in their package settings so Home Assistant and Compose can pull without credentials. Ensure organisation policy permits Actions package publishing. Pull-request CI remains build-only and never logs in or pushes images. See RELEASE-CHECK.md for validation limits.

Further reading

• CONTRIBUTING.md
• HACS: plugin (dashboard) publishing requirements
• Home Assistant developer docs: app configuration
• GitHub Docs: about wikis