mirror of
https://github.com/jpawlowski/hass.tibber_prices.git
synced 2026-03-29 21:03:40 +00:00
docs(workflow): document release automation and validation patterns
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:
parent
d7a145d678
commit
6ebcdc90c0
1 changed files with 44 additions and 9 deletions
53
.github/copilot-instructions.md
vendored
53
.github/copilot-instructions.md
vendored
|
|
@ -137,16 +137,18 @@ This ensures the documentation stays accurate and useful as the codebase evolves
|
|||
"selector": {
|
||||
"volatility": {
|
||||
"options": {
|
||||
"LOW": "Low",
|
||||
"MODERATE": "Moderate",
|
||||
"HIGH": "High"
|
||||
"low": "Low",
|
||||
"moderate": "Moderate",
|
||||
"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
|
||||
# ✅ CORRECT with translation_key
|
||||
|
|
@ -712,19 +714,44 @@ The "Impact:" section bridges technical commits and future release notes:
|
|||
**Recommended Release Workflow:**
|
||||
|
||||
```bash
|
||||
# Step 1: Prepare release (bumps manifest.json + creates tag)
|
||||
./scripts/prepare-release 0.3.0
|
||||
# Step 1: Get version suggestion (analyzes commits since last release)
|
||||
./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 show v0.3.0
|
||||
|
||||
# Step 3: Push when ready
|
||||
# Step 5: Push when ready
|
||||
git push origin main v0.3.0
|
||||
|
||||
# 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):**
|
||||
|
||||
```bash
|
||||
|
|
@ -1094,7 +1121,15 @@ We use **Ruff** (which replaces Black, Flake8, isort, and more) as our sole lint
|
|||
**Function organization:**
|
||||
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).
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue