95 lines
4.0 KiB
Markdown
95 lines
4.0 KiB
Markdown
# Repository instructions
|
|
|
|
## Language
|
|
|
|
Use French when communicating with the user unless they ask otherwise. All new
|
|
technical artifacts must be in English: code, identifiers, variable and
|
|
function names, Home Assistant entity and sensor names, log messages, comments,
|
|
test names, configuration keys, and technical documentation. Do not rename
|
|
existing French identifiers or entities unless explicitly requested.
|
|
|
|
## Context
|
|
|
|
This repository is an AppDaemon configuration for Home Assistant. Python apps
|
|
in `apps/` control real equipment, including heating, shutters, lighting, a
|
|
projector, and a television. Application configuration is in `apps/apps.yaml`,
|
|
supplemented by YAML files in `apps/global/` and `apps/rooms/`. Runtime
|
|
configuration is in `appdaemon.yaml`.
|
|
|
|
`apps/ad_toolbox` is a shared Git submodule. It provides the base classes,
|
|
conditions, virtual sensors, and logging used by the apps. Only change it when
|
|
the request explicitly concerns that component. Do not update its revision or
|
|
discard its local changes without approval.
|
|
|
|
## Security and operations
|
|
|
|
- Never display, copy into responses, or commit tokens, passwords,
|
|
`secrets.yaml`, `apps/theframe_token.txt`, or persisted data in `apps/data/`.
|
|
Refer to their paths and redact sensitive values in diagnostics.
|
|
- Do not start a second AppDaemon instance, rerun `dockerStart.sh`, or execute
|
|
`archiveLogs.sh` manually while the service is running. The archive script
|
|
moves active log files.
|
|
- Do not restart the container, send device commands, or change heating
|
|
setpoints unless the user explicitly requests it. To test heating logic, use
|
|
mocks first or `send_commands: false` where available.
|
|
- Local AppDaemon-core and startup-script patches may exist outside this
|
|
persistent repository. Read `docs/appdaemon-local-changes.md` and
|
|
`docs/appdaemon-upgrade-rollback-instructions.md` before upgrading or
|
|
changing the runtime. Do not overwrite or "clean up" these patches.
|
|
|
|
## Logs and diagnosis
|
|
|
|
When asked to investigate a warning, error, or runtime behavior, inspect
|
|
`/conf/logs` first:
|
|
|
|
1. `appdaemon.log`, `error.log`, and `virtualsensors.log` for the current run;
|
|
2. `archive/<timestamp>/` for previous runs;
|
|
3. `memory_usage.csv` when memory use is suspected.
|
|
|
|
Always inspect the lines following a warning: a successful reconnection or
|
|
recovery can make an incident transient. Distinguish application problems from
|
|
Home Assistant, MQTT, or hardware connectivity losses.
|
|
|
|
## Changes
|
|
|
|
- Follow the style and conventions of the app or module being changed. Apps
|
|
often inherit from `SmartObject` and use `SmartCondition`; do not bypass
|
|
these abstractions without a clear reason.
|
|
- Keep an app, its `apps/apps.yaml` entry, its Home Assistant entities, and any
|
|
related `apps/global/` or `apps/rooms/` configuration consistent.
|
|
- Preserve AppDaemon lifecycle behavior: cancel timers, tasks, listeners, and
|
|
sockets on reload or termination when a change introduces them.
|
|
- Do not overwrite or reorganize the user's existing work. Keep diffs limited
|
|
to the requested change.
|
|
- Update documentation in `docs/` when operational behavior, a hardware
|
|
protocol, or a deployment procedure changes.
|
|
|
|
## Validation
|
|
|
|
The project uses `unittest`; no formatter or linter is configured. After a
|
|
Python change, run the focused test when one exists, for example:
|
|
|
|
```sh
|
|
python3 -m unittest discover -s tests -p 'test_vertex2.py' -v
|
|
python3 -m unittest discover -s tests -p 'test_boilerclimate.py' -v
|
|
python3 -m unittest discover -s tests -p 'test_samsungtheframe_async.py' -v
|
|
```
|
|
|
|
For shared changes or before a broader delivery:
|
|
|
|
```sh
|
|
python3 -m unittest discover -s tests -v
|
|
python3 -m unittest discover -s apps/ad_toolbox/unit_tests -p 'test_*.py' -v
|
|
```
|
|
|
|
The legacy YAML test runner for `ad_toolbox` is:
|
|
|
|
```sh
|
|
python3 apps/ad_toolbox/unittests.py
|
|
```
|
|
|
|
After a shell-script change, validate syntax at minimum with
|
|
`sh -n <script>`. Changes to the VS Code extension in
|
|
`apps/ad_toolbox/vscode-appdaemon/` must also follow its own `AGENTS.md`,
|
|
including compilation, packaging, and installation.
|