From 1fc345c56970fa20540fab6cebb7b9f56c48cc44 Mon Sep 17 00:00:00 2001 From: eduard256 Date: Thu, 11 Dec 2025 16:52:53 +0000 Subject: [PATCH] Add release process documentation --- RELEASE.md | 281 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 281 insertions(+) create mode 100644 RELEASE.md diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 0000000..f2cc777 --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,281 @@ +# Release Process Documentation + +This document describes the complete release process for Strix and its Home Assistant add-on. + +## Overview + +Strix consists of two repositories: +- **Strix** - Main application (Go binary, Docker image) +- **hassio-strix** - Home Assistant add-on + +Both repositories must be released together to maintain version consistency. + +## Version Files + +### Strix Repository + +| File | Line | Purpose | +|------|------|---------| +| `cmd/strix/main.go` | 23 | Application version constant | +| `webui/package.json` | 3 | Frontend version | +| `CHANGELOG.md` | Top | Release notes | + +### hassio-strix Repository + +| File | Line | Purpose | +|------|------|---------| +| `strix/config.json` | 3 | Home Assistant add-on version | +| `strix/CHANGELOG.md` | Top | Release notes | + +## Release Workflow + +### Prerequisites + +1. Ensure you're on the `develop` branch with all changes committed +2. All tests pass: `go test ./...` +3. Application builds successfully: `go build ./...` + +### Step 1: Update Strix Repository + +```bash +cd /home/user/Strix +git checkout develop + +# 1. Update version in code +# Edit cmd/strix/main.go - line 23 +# Version = "1.0.X" + +# 2. Update frontend version +# Edit webui/package.json - line 3 +# "version": "1.0.X" + +# 3. Update CHANGELOG.md +# Add new section at the top: +# ## [1.0.X] - YYYY-MM-DD +# ### Fixed/Added/Changed +# - Description of changes + +# 4. Commit version bump +git add cmd/strix/main.go webui/package.json CHANGELOG.md +git commit -m "Release v1.0.X: Brief description" + +# 5. Merge to main +git checkout main +git merge develop --no-ff -m "Merge develop into main for v1.0.X release" + +# 6. Create tag +git tag -a v1.0.X -m "Release v1.0.X: Brief description" + +# 7. Push everything +git push origin main --tags +git push origin develop +``` + +### Step 2: Update hassio-strix Repository + +```bash +cd /home/user/hassio-strix + +# 1. Update add-on version +# Edit strix/config.json - line 3 +# "version": "1.0.X" + +# 2. Update CHANGELOG +# Edit strix/CHANGELOG.md - add same section as in Strix + +# 3. Commit and push +git add strix/config.json strix/CHANGELOG.md +git commit -m "Release v1.0.X: Brief description" +git push origin main + +# 4. Create tag +git tag -a v1.0.X -m "Release v1.0.X: Brief description" +git push origin --tags +``` + +### Step 3: Verify GitHub Actions + +After pushing tags, GitHub Actions will automatically: + +**Strix (eduard256/Strix):** +- ✅ `release.yml` - GoReleaser creates GitHub Release with binaries +- ✅ `docker.yml` - Builds and pushes Docker images to Docker Hub + - Tags: `1.0.X`, `1.0`, `1`, `latest` + - Platforms: `linux/amd64`, `linux/arm64` + +**hassio-strix (eduard256/hassio-strix):** +- ✅ `builder.yml` - Builds and pushes HA add-on to GHCR + - Image: `ghcr.io/eduard256/hassio-strix-{arch}` + - Architectures: `amd64`, `aarch64` + +Check status: +```bash +# Check Strix actions +gh run list --repo eduard256/Strix --limit 5 + +# Check hassio-strix actions +gh run list --repo eduard256/hassio-strix --limit 5 +``` + +### Step 4: Verify Release + +1. **GitHub Release**: https://github.com/eduard256/Strix/releases/tag/v1.0.X + - Should have binaries for all platforms + +2. **Docker Hub**: https://hub.docker.com/r/eduard256/strix/tags + - Should show new version tag + +3. **GHCR**: https://github.com/eduard256/hassio-strix/pkgs/container/hassio-strix-amd64 + - Should show new version + +4. **Home Assistant Add-on Store**: + - Users will see update notification automatically + +## Quick Release Script + +For automated release, use this script: + +```bash +#!/bin/bash +# release.sh - Automated release script + +VERSION=$1 + +if [ -z "$VERSION" ]; then + echo "Usage: ./release.sh 1.0.X" + exit 1 +fi + +echo "🚀 Releasing v$VERSION" + +# Strix repo +cd /home/user/Strix +git checkout develop + +# Update versions +sed -i "s/Version = \".*\"/Version = \"$VERSION\"/" cmd/strix/main.go +sed -i "s/\"version\": \".*\"/\"version\": \"$VERSION\"/" webui/package.json + +# Update CHANGELOG (manual step reminder) +echo "⚠️ Please update CHANGELOG.md manually" +read -p "Press enter when done..." + +# Commit and merge +git add cmd/strix/main.go webui/package.json CHANGELOG.md +git commit -m "Release v$VERSION" +git checkout main +git merge develop --no-ff -m "Merge develop into main for v$VERSION release" +git tag -a "v$VERSION" -m "Release v$VERSION" +git push origin main --tags +git push origin develop + +# hassio-strix repo +cd /home/user/hassio-strix + +# Update version +sed -i "s/\"version\": \".*\"/\"version\": \"$VERSION\"/" strix/config.json + +# Update CHANGELOG (manual step reminder) +echo "⚠️ Please update strix/CHANGELOG.md manually" +read -p "Press enter when done..." + +# Commit and tag +git add strix/config.json strix/CHANGELOG.md +git commit -m "Release v$VERSION" +git push origin main +git tag -a "v$VERSION" -m "Release v$VERSION" +git push origin --tags + +echo "✅ Release v$VERSION complete!" +echo "Check GitHub Actions:" +echo " - https://github.com/eduard256/Strix/actions" +echo " - https://github.com/eduard256/hassio-strix/actions" +``` + +## Troubleshooting + +### Docker Build Fails + +**Symptom**: "Docker Hub Description" step shows `Forbidden` error + +**Cause**: Docker Hub Personal Access Token expired or lacks permissions + +**Solution**: +1. Go to Docker Hub → Account Settings → Security → Personal Access Tokens +2. Create new token with `Read, Write, Delete` scopes +3. Update GitHub secret: https://github.com/eduard256/Strix/settings/secrets/actions +4. Update `DOCKER_TOKEN` secret + +**Note**: This only affects README updates on Docker Hub. Docker images still build successfully. + +### Home Assistant Add-on Build Fails + +**Symptom**: Builder workflow fails + +**Solution**: +1. Check `strix/Dockerfile` for correct Go version +2. Verify `strix/build.yaml` has correct base images +3. Check logs: `gh run view --repo eduard256/hassio-strix --log` + +### Version Mismatch + +**Symptom**: Strix shows different version than add-on + +**Solution**: +1. Verify both `cmd/strix/main.go` and `strix/config.json` have same version +2. Ensure both repositories have matching tags: `git tag -l` +3. If needed, delete wrong tag: `git tag -d v1.0.X && git push origin :refs/tags/v1.0.X` + +## Release Checklist + +Before releasing: +- [ ] All changes merged to `develop` +- [ ] Tests pass: `go test ./...` +- [ ] Build succeeds: `go build ./...` +- [ ] CHANGELOG.md updated in both repos +- [ ] Version numbers match in all files +- [ ] Commit messages don't mention AI/Claude Code + +After releasing: +- [ ] GitHub Release created with binaries +- [ ] Docker images pushed to Docker Hub +- [ ] HA add-on images pushed to GHCR +- [ ] Home Assistant users can see update + +## Version Numbering + +Strix follows [Semantic Versioning](https://semver.org/): + +- **MAJOR.MINOR.PATCH** (e.g., 1.0.9) +- **MAJOR**: Breaking changes +- **MINOR**: New features (backward compatible) +- **PATCH**: Bug fixes + +## GitHub Actions Overview + +### Strix Repository + +**Triggers:** +- `release.yml`: On push tag `v*` +- `docker.yml`: On push tag `v*` or push to `main` +- `ci.yml`: On push to any branch + +**Secrets Required:** +- `GITHUB_TOKEN` (automatic) +- `DOCKER_USERNAME` +- `DOCKER_TOKEN` + +### hassio-strix Repository + +**Triggers:** +- `builder.yml`: On push tag `v*` or manual workflow dispatch + +**Secrets Required:** +- `GITHUB_TOKEN` (automatic) + +## Notes + +- Always release both repositories together +- Keep version numbers synchronized +- Test in Home Assistant Ingress mode before releasing +- Docker/direct mode should work without changes (backward compatibility)