Add release process documentation
This commit is contained in:
eduard256
+281
@@ -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 <run-id> --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)
|
||||
Reference in New Issue
Block a user