alexei.dolgolyov
ba34d6f677
Always ask before committing or pushing changes. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
95 lines
3.2 KiB
Markdown
95 lines
3.2 KiB
Markdown
# Home Assistant Automation Blueprints
|
|
|
|
This repository contains automation blueprints for Home Assistant OS.
|
|
|
|
## Git Workflow
|
|
|
|
**Do not commit or push automatically.** Always ask before committing or pushing changes.
|
|
|
|
## Code Review Guidelines
|
|
|
|
When reviewing or refactoring blueprint files:
|
|
|
|
1. **Code Quality** - Improve overall structure and readability
|
|
2. **Bug Fixes** - Identify and fix obvious or critical bugs and mistakes
|
|
3. **Spelling & Grammar** - Correct any spelling or grammatical errors
|
|
4. **Documentation** - Add comments to make the code easier to read and understand
|
|
5. **User-Friendly Messages** - Use entity friendly names instead of entity IDs in notification messages
|
|
|
|
## Versioning
|
|
|
|
After any change to repository content (blueprints, documentation, or other files), update the `version` field in `manifest.json` using semantic versioning:
|
|
|
|
- **Major** (X.0.0) - Breaking changes or major new features
|
|
- **Minor** (0.X.0) - New features, enhancements, or significant improvements
|
|
- **Patch** (0.0.X) - Bug fixes, typos, small tweaks, or documentation updates
|
|
|
|
## Repository Structure
|
|
|
|
Each blueprint is organized in its own folder:
|
|
|
|
```text
|
|
Common/
|
|
Blueprint Name/
|
|
blueprint.yaml # The automation blueprint
|
|
README.md # Detailed documentation
|
|
Zigbee/
|
|
Blueprint Name/
|
|
blueprint.yaml
|
|
README.md
|
|
```
|
|
|
|
### Working with Blueprints
|
|
|
|
**When modifying a blueprint:**
|
|
|
|
1. Edit `blueprint.yaml` for code changes
|
|
2. Update `README.md` if the change affects features, configuration, or behavior
|
|
3. Keep the blueprint header short (4-5 lines) - detailed docs go in README.md
|
|
|
|
**When creating a new blueprint:**
|
|
|
|
1. Create a new folder named after the blueprint (e.g., `Common/My New Blueprint/`)
|
|
2. Add `blueprint.yaml` with a short header referencing README.md
|
|
3. Add `README.md` with full documentation (features, how it works, configuration)
|
|
|
|
**Blueprint header format:**
|
|
|
|
```yaml
|
|
# Blueprint Name
|
|
# One-line description of what it does.
|
|
# See README.md for detailed documentation.
|
|
#
|
|
# Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
|
|
```
|
|
|
|
When any blueprint file is moved ask if I need to update the link somewhere else.
|
|
|
|
## Jinja2 Whitespace Issue
|
|
|
|
Home Assistant evaluates all blueprint variables before conditions are checked. When a variable's Jinja2 template contains whitespace (newlines, indentation), that whitespace gets included in the output even if the template logic produces an empty string.
|
|
|
|
**Problem:** Using a variable like `{{ my_variable }}` in string replacements will include unwanted whitespace.
|
|
|
|
**Solution:** Compute complex values inline where they're used, with `{%- -%}` whitespace control:
|
|
|
|
```yaml
|
|
# BAD - whitespace from my_list variable will be included
|
|
my_list: >
|
|
{% for item in items %}
|
|
{{ item }}
|
|
{% endfor %}
|
|
|
|
result: "{{ template | replace('{items}', my_list) }}"
|
|
|
|
# GOOD - inline computation with whitespace control
|
|
result: >
|
|
{%- set ns = namespace(items = '') -%}
|
|
{%- for item in items -%}
|
|
{%- set ns.items = ns.items ~ item -%}
|
|
{%- endfor -%}
|
|
{{ template | replace('{items}', ns.items) }}
|
|
```
|
|
|
|
This pattern is used throughout the Immich Album Watcher blueprint for `common_date`, `common_location`, `video_warning`, and `periodic_albums_list`.
|