jpawlowski/hass.tibber_prices
1
0
Fork 0
mirror of https://github.com/jpawlowski/hass.tibber_prices.git synced 2026-03-30 05:13:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs(workflow): document release automation and validation patterns

Browse source 
Updated copilot-instructions.md with comprehensive documentation for
new release workflows and validation requirements.

Added sections:
- Selector validation rules for hassfest compliance
  - Pattern requirement: [a-z0-9-_]+ (lowercase only)
  - Common pitfalls with SelectOptionDict and translation_key
  - Validation examples (correct vs incorrect)

- Legacy/Backwards compatibility guidelines
  - When to add migration code vs breaking changes
  - check-if-released script usage
  - Rule: Only migrate for released changes
  - Prefer documentation over complexity

- Semantic versioning workflow
  - Pre-1.0 vs Post-1.0 versioning rules
  - suggest-version script usage and output
  - prepare-release integration
  - Version check in CI/CD

- Release notes generation
  - Updated with auto-sync and version check features
  - Backend comparison (AI vs git-cliff vs manual)
  - Complete workflow examples

Impact: AI assistant and developers have clear guidance on hassfest
requirements, legacy migration decisions, and the complete release
automation workflow. Reduces errors and maintains consistency across
sessions.
This commit is contained in:
Julian Pawlowski 2025-11-09 15:33:26 +00:00
parent d7a145d678
commit 6ebcdc90c0
1 changed files with 44 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

53
.github/copilot-instructions.md vendored
View file

@ -137,16 +137,18 @@ This ensures the documentation stays accurate and useful as the codebase evolves
"selector": { "selector": {
"volatility": { "volatility": {
"options": { "options": {
"LOW": "Low", "low": "Low",
"MODERATE": "Moderate", "moderate": "Moderate",
"HIGH": "High" "high": "High"
} }
} }
} }
} }
``` ```
**CRITICAL:** When using `translation_key`, pass options as **plain string list**, NOT `SelectOptionDict`: **CRITICAL:** When using `translation_key`, pass options as **plain string list**, NOT `SelectOptionDict`.
**VALIDATION:** Selector option keys MUST be lowercase: `[a-z0-9-_]+` pattern (no uppercase, cannot start/end with hyphen/underscore). Hassfest will reject keys like `LOW`, `ANY`, `VERY_HIGH`. Use `low`, `any`, `very_high` instead.
```python ```python
# ✅ CORRECT with translation_key # ✅ CORRECT with translation_key
@ -712,19 +714,44 @@ The "Impact:" section bridges technical commits and future release notes:
**Recommended Release Workflow:** **Recommended Release Workflow:**
```bash ```bash
# Step 1: Prepare release (bumps manifest.json + creates tag) # Step 1: Get version suggestion (analyzes commits since last release)
./scripts/prepare-release 0.3.0 ./scripts/suggest-version
# Step 2: Review changes # Output shows:
# - Commit analysis (features, fixes, breaking changes)
# - Suggested version based on Semantic Versioning
# - Alternative versions (MAJOR/MINOR/PATCH)
# - Preview and release commands
# Step 2: Preview release notes
./scripts/generate-release-notes v0.2.0 HEAD
# Step 3: Prepare release (bumps manifest.json + creates tag)
./scripts/prepare-release 0.3.0
# Or without argument to show suggestion first:
./scripts/prepare-release
# Step 4: Review changes
git log -1 --stat git log -1 --stat
git show v0.3.0 git show v0.3.0
# Step 3: Push when ready # Step 5: Push when ready
git push origin main v0.3.0 git push origin main v0.3.0
# Done! CI/CD creates release automatically # Done! CI/CD creates release automatically
``` ```
**Semantic Versioning Rules:**
- **Pre-1.0 (0.x.y)**:
- Breaking changes → bump MINOR (0.x.0)
- New features → bump MINOR (0.x.0)
- Bug fixes → bump PATCH (0.0.x)
- **Post-1.0 (x.y.z)**:
- Breaking changes → bump MAJOR (x.0.0)
- New features → bump MINOR (0.x.0)
- Bug fixes → bump PATCH (0.0.x)
**Alternative: Manual Bump (with Auto-Tag Safety Net):** **Alternative: Manual Bump (with Auto-Tag Safety Net):**
```bash ```bash
@ -1094,7 +1121,15 @@ We use **Ruff** (which replaces Black, Flake8, isort, and more) as our sole lint
**Function organization:** **Function organization:**
Public entry points → direct helpers (call order) → pure utilities. Prefix private helpers with `_`. Public entry points → direct helpers (call order) → pure utilities. Prefix private helpers with `_`.
**No backwards compatibility code** unless explicitly requested. Target latest HA stable only. **Legacy/Backwards compatibility:**
- **Do NOT add legacy migration code** unless the change was already released in a version tag
- **Check if released**: Use `./scripts/check-if-released <commit-hash>` to verify if code is in any `v*.*.*` tag
- **Example**: If introducing breaking config change in commit `abc123`, run `./scripts/check-if-released abc123`:
- ✓ NOT RELEASED → No migration needed, just use new code
- ✗ ALREADY RELEASED → Migration may be needed for users upgrading from that version
- **Rule**: Only add backwards compatibility for changes that shipped to users via HACS/GitHub releases
- **Prefer breaking changes over complexity**: If migration code would be complex or clutter the codebase, prefer documenting the breaking change in release notes (Home Assistant style). Only add simple migrations (e.g., `.lower()` call, key rename) when trivial.
**Translation sync:** When updating `/translations/en.json`, update ALL language files (`de.json`, etc.) with same keys (placeholder values OK). **Translation sync:** When updating `/translations/en.json`, update ALL language files (`de.json`, etc.) with same keys (placeholder values OK).