mirror of
https://github.com/Matysh/houseplan-card
synced 2026-09-29 03:09:36 +00:00
Matysh
ae10b2861b
The owner stopped using GitHub Projects. Most of this is wording, but one part was not: release-prerelease.mjs talked to the Project in code. finishIssues looked up the project id, listed its items and its Status=Done option, and threw when an issue was missing from the board — so the first release that closed an issue would have died on a step with nothing to do with publishing. Found by reading rather than by releasing, which was luck. Closing issues stays, and now strips the status label first. That order is not cosmetic: the invariant that a closed issue carries no status label has broken twice already, both times because a manual step did it the other way round. The close-merged job already does it in this order. The documents now say labels and only labels. The explicit "no longer used" lines are kept on purpose, in PROCESS.md and next to the code that used to sync: a decision that vanishes quietly gets reintroduced a month later by someone who never knew it was made. Issue: #139 User-Visible: no
64 lines
3.1 KiB
Markdown
64 lines
3.1 KiB
Markdown
# Contributing to House Plan
|
|
|
|
Thanks for your interest! The project is one HACS package: a storage **integration**
|
|
(`custom_components/houseplan/`, Python) and a **Lovelace card** (`src/`, TypeScript + Lit).
|
|
|
|
## Changelog
|
|
|
|
User-visible changes go into **both** changelogs in the same commit:
|
|
`docs/CHANGELOG.md` (English) and `docs/CHANGELOG.ru.md` (Russian). Entries
|
|
older than v1.42.0 exist only in the English file — no need to backfill them.
|
|
|
|
## Where to ask
|
|
|
|
Not sure whether something is a bug, or just want to discuss an idea before
|
|
writing code? The **[Telegram chat @ha_houseplan](https://t.me/ha_houseplan)**
|
|
is the quickest route to the author and other users. Bugs and concrete feature
|
|
requests still belong in [issues](https://github.com/Matysh/houseplan-card/issues).
|
|
|
|
## Backlog and work status
|
|
|
|
[GitHub Issues](https://github.com/Matysh/houseplan-card/issues) are the only
|
|
active backlog. An issue owns scope and acceptance criteria; its **labels** own
|
|
priority and workflow status — `PROCESS.md` §9 holds the vocabulary. Before
|
|
starting planned work, link it to an existing issue or create one, and keep it
|
|
current until the verified result is closed. Design specs and ADRs may support an
|
|
issue, but they do not replace it or maintain a separate checklist.
|
|
|
|
## Five-minute setup
|
|
|
|
```bash
|
|
git clone https://github.com/Matysh/houseplan-card && cd houseplan-card
|
|
npm ci # frontend toolchain
|
|
npm run typecheck # tsc --noEmit (strict)
|
|
npm test # node:test — pure logic, i18n parity, tap-action security
|
|
npm run build # tsc + rollup → dist/houseplan-card.js
|
|
pip install pytest voluptuous && python -m pytest tests_backend -q # pure backend tests
|
|
npm install # also installs .githooks through the prepare script
|
|
```
|
|
|
|
The HA-harness backend tests (`tests_backend/test_ha_*.py`) need Python ≥3.13 and
|
|
`pytest-homeassistant-custom-component home-assistant-frontend`; CI runs them on
|
|
every push — locally they are skipped when `homeassistant` is not importable.
|
|
|
|
## Ground rules
|
|
|
|
- **Docs in the same commit**: CHANGELOG entry for user-visible changes;
|
|
`docs/STATUS.md` for state changes; `docs/DEVELOPMENT.md` for new gotchas.
|
|
- Every UI string goes through `src/i18n/<lang>.json` (tests enforce en/ru key parity).
|
|
Adding a language = adding one JSON file + registering it in `src/i18n.ts`.
|
|
- The built card must be committed in sync: `cp dist/houseplan-card.js
|
|
custom_components/houseplan/frontend/` (CI compares them byte-for-byte).
|
|
- Tap actions have a security model (locks/alarms never toggle from the plan) —
|
|
see `resolveToggleIntent` in `src/device-toggle.ts`; don't weaken it.
|
|
- Every commit follows the issue and trailer contract in `PROCESS.md`.
|
|
- Follow the Integration Quality Scale where applicable —
|
|
`custom_components/houseplan/quality_scale.yaml` tracks the self-assessment.
|
|
|
|
## Architecture
|
|
|
|
Start with `docs/ARCHITECTURE.md` (data model, WS API, coordinate system) and
|
|
`docs/STATUS.md` (current state). Release: bump the version in `package.json`,
|
|
`manifest.json`, `const.py`, `CARD_VERSION`, tag `vX.Y.Z`, publish a GitHub release —
|
|
the workflow attaches the card bundle.
|