Release Stable

Create Stable Production Release

Create a STABLE release for production use.

Current version: Check package.json for current version.

⚠️ CRITICAL TAG FORMAT RULE

NEVER use 'v' prefix in git tags!

• ✅ CORRECT: 1.5.0
• ❌ WRONG: v1.5.0

The GitHub workflows expect tags WITHOUT 'v' prefix. Using 'v' will cause workflow failures. All scripts (bump-version.sh, create-release.sh) already create tags without 'v'. Never create tags manually - always use the scripts.

Intelligent Workflow

The workflow adapts automatically based on the current version:

From beta (1.5.0-beta.3 → 1.5.0) → Automatic finalization, no analysis needed Direct stable release (1.4.0 → 1.5.0) → AI analyzes commits and suggests version type with warning

Phase 1: Release Type Detection

Automatically detect release scenario:

1. Detect release scenario:

   • Current version: 1.5.0-beta.3 → Finalize beta (automatic, no validation)
   • Current version: 1.4.0 (stable) → Direct release (requires AI analysis + warning)

2. For finalize beta:

   • Strip -beta.N suffix automatically
   • Skip commit analysis (already done during beta)
   • Faster workflow (3-5 min)

3. For direct stable release:

   • Show WARNING about skipping beta testing (risky)
   • Run commit analysis: npm run analyze:commits
   • Analyze commit types (feat, fix, BREAKING CHANGE)
   • Determine version bump type (patch/minor/major)
   • Present detailed validation with option to create beta instead

Phase 2A: Finalize Beta (Automatic)

Current: 1.5.0-beta.3 → Stable: 1.5.0

Present automatic finalization message:

• Current version and target stable version
• Note that version type was already determined during beta
• No additional analysis or validation required
• Proceed automatically to release notes and validation

No user validation required → Proceeds directly to Phase 3

Phase 2B: Direct Stable Release (Requires Validation)

Current: 1.4.0 → Proposed: 1.5.0

Beta Testing Warning

Present warning about direct stable release:

• Risks: No community feedback, untested in real environments, bugs reach production, harder rollback
• Recommendation: Create beta first
• User options:
  • [1] YES - Continue with direct release (risky)
  • [2] CREATE BETA INSTEAD - Safer approach
  • [3] CANCEL - Abort

If user chooses [2] CREATE BETA: Stop and use release-beta skill

If user chooses [1] PROCEED: Show detailed AI analysis

AI Semantic Analysis (Direct Release Only)

Present detailed analysis with:

• Current version and proposed version
• Warning about skipping beta
• Commit breakdown (feat, fix, breaking, etc.)
• AI reasoning with confidence level
• Recommendation to test as beta first
• Key commits (most impactful)
• User decision options:
  • [1] APPROVE - Proceed with AI suggestion (skipping beta)
  • [2] DOWNGRADE TO PATCH - Override AI (skipping beta)
  • [3] UPGRADE TO MAJOR - Override AI (skipping beta)
  • [4] CREATE BETA INSTEAD - Safer approach (recommended)
  • [5] VIEW COMMITS - Show full commit list
  • [6] CANCEL - Abort safely

Phase 3: Release Notes Generation & Editing

Automatically:

1. Generate release notes (bash scripts/generate-release-notes.sh)
2. AI-powered editing:
   • Remove noise (version bumps, merges, CI commits, deps updates)
   • Enhance features/fixes (bold title + detailed description)
   • Translate to French (same detail level)
   • Remove beta testing section (not needed for stable)
   • Add upgrade instructions if needed
   • Remove TODO markers
3. Format for GitHub (bash scripts/format-release-notes.sh)

Phase 4: Quality Validation (BLOCKING)

All must pass:

A. Release notes validation (scripts/validate-release-notes.sh)

• Required sections EN/FR
• No TODO
• No beta testing section
• Bold features

B. Code quality (17 checks) (scripts/check-release-ready.sh)

1. Git clean 2. Branch main 3. Up-to-date 4. Deps installed 5. Lint 6. Type-check 7. Build 8. Version consistency 9. No FIXME 10. CHANGELOG 11. manifest.json 12. hacs.json 13. No secrets 14. Python syntax 15. README 16. LICENSE 17. Smoke tests ready

C. Smoke tests (15 tests) (npm run test:smoke)

Phase 5: Final Approval & Publication

For finalize beta:

Present approval with:

• Version and finalization info
• Note that beta testing completed successfully
• Changes summary (features, bug fixes) since last stable
• Validation results
• What happens if approved

User options:

• [1] APPROVE - Publish stable release
• [2] REQUEST CHANGES - Modify release notes
• [3] VIEW FULL NOTES - See complete file
• [4] CANCEL - Abort

For direct stable release:

Present approval with:

• Version and bump type
• Warning about skipping beta testing
• Changes summary
• Validation results
• Reminder to monitor closely

User options:

• [1] APPROVE - Publish stable release (skipping beta)
• [2] CREATE BETA INSTEAD - Safer approach
• [3] REQUEST CHANGES - Modify release notes
• [4] VIEW FULL NOTES - See complete file
• [5] CANCEL - Abort

Phase 6: Publication (Only after approval)

For finalize beta (automatic version):

1. Bump version (bash scripts/bump-version.sh release)
   • Strips -beta.N: 1.5.0-beta.3 → 1.5.0
2. Update release notes with final version
3. Commit + tag (git commit + git tag)
4. Push (git push && git push --tags)
5. Report success with forum links

For direct stable release (explicit version type):

1. Bump version (bash scripts/bump-version.sh release <patch|minor|major>)
   • Example: bash scripts/bump-version.sh release minor → 1.5.0
2. Update release notes with final version
3. Commit + tag (git commit + git tag)
4. Push (git push && git push --tags)
5. Report success with forum links

GitHub Actions automatically:

• Builds project
• Runs smoke tests
• Creates ZIP
• Creates stable release
• Sends Discord notification (public announcement)
• Cleans up RELEASE_NOTES.md

Manual step:

• Open forum threads: npm run forums:open
• Post release announcement (templates provided)

Quality Standards

Release notes: EN+FR equal quality, no TODO, detailed explanations, user-focused, clean, no beta testing section

Code: 17 checks passed, 15 smoke tests passed, lint+type-check passed, build succeeded

Version decision:

• Finalize beta: Automatic, no validation
• Direct release: AI analyzes commits, warns about skipping beta, requires user validation

Options

Dry Run

--dry-run

Runs everything, creates commit+tag locally, STOPS before push. Nothing published. To undo: git reset HEAD~1 && git tag -d X.Y.Z

Skip Approval (Final approval only)

--skip-approval

Shows summary but auto-approves final publication. Still shows warning and requires version decision for direct releases. ⚠️ Use with extreme caution.

Logs

Every release logged to: .opencode/logs/release-stable-{timestamp}.log

Contains: timestamps, detection logic, commit analysis (if direct), AI reasoning, warnings shown, user decisions, git hashes, URLs, duration

Common Errors

Validation fails → Fix issues, re-run command Smoke tests fail → Check npm run test:smoke, fix, re-run Build fails → Run npm run build, fix errors, re-run Push fails → git pull --rebase, re-run Tag exists → git tag -d X.Y.Z then re-run Ambiguous commits (direct release) → AI asks you to decide manually Beta recommended → Use release-beta skill first for safer release

Related Commands

Before stable release:

• Recommended: Use release-beta skill (test first)
• Check status: Use release-check skill

After stable release:

• Hotfix needed → Use release-stable skill again (creates patch: 1.5.0 → 1.5.1)
• Critical issue → Use release-rollback skill
• Announce → npm run forums:open

Release Type Detection Logic

Important

• Finalize beta: Automatic and fast (no validation, already tested)
• Direct stable: Requires AI analysis + shows warning about skipping beta + requires your validation
• Best practice: Always test with beta first (release-beta → test → release-stable)
• All validations are blocking (must pass)
• Idempotent (safe to re-run)
• Logs everything
• Time: 3-5 min (finalize) or 5-10 min (direct release)

Scripts Used:

• scripts/analyze-commits.sh - Commit analysis (direct release only)
• scripts/bump-version.sh release [patch|minor|major] - Version bumping
• scripts/generate-release-notes.sh - Release notes generation
• scripts/format-release-notes.sh - Formatting
• scripts/validate-release-notes.sh - Validation
• scripts/check-release-ready.sh - Code quality checks

Forum Announcement: After successful release, use npm run forums:open to announce on Home Assistant Community Forum and HACF.