🚀 Release Process

This guide explains how to publish a new version of MyAstroBoard, including creating releases and publishing Docker images.

📋 Prerequisites

Write access to the repository
Git installed locally
Understanding of Semantic Versioning

🏷️ Versioning Strategy

MyAstroBoard follows Semantic Versioning:

MAJOR version (x.0.0): Incompatible API changes, breaking changes
MINOR version (0.x.0): New features, backwards-compatible
PATCH version (0.0.x): Bug fixes, backwards-compatible

📦 Release Process

Step 1: Prepare the Release

Ensure all changes are merged to the main branch:
```
git checkout main
git pull origin main
```
Check CHANGELOG.md: the ## [Unreleased] section at the top of CHANGELOG.md is what becomes the GitHub release notes - it should already be up to date, since every feature//fix/ PR is required to add its own entry there (see CONTRIBUTING.md#changelog). Fix anything that reads like a novel before tagging - it goes into the release notes as-is.

Update the VERSION file:

# Edit the VERSION file with the new version number
echo "0.2.0" > VERSION

Review and test changes:
- Run all tests: pytest --cov=backend tests/
- Build locally: docker compose build
- Test the application thoroughly

Commit the version change:

git add VERSION
git commit -m "chore: bump version to 0.2.0"
git push origin main

Step 2: Create a Git Tag

Create and push a version tag. The tag must follow the format v*.*.* (e.g., v0.2.0):

# Create an annotated tag
git tag -a v0.2.0 -m "Release v0.2.0"

# Push the tag to GitHub
git push origin v0.2.0

Step 3: Automated Build and Release

Once you push the tag, the GitHub Actions workflow will automatically:

✅ Trigger the docker-publish.yml workflow
✅ Build the Docker image for linux/amd64 and linux/arm64
✅ Publish the image to Docker Hub (myastroboard/myastroboard) and to the GitHub Container Registry (ghcr.io/myastroboard/myastroboard), with four tags each:
- 0.2.0 (specific version)
- 0.2 (minor version)
- 0 (major version)
- latest
✅ Create a GitHub Release, with release notes built from CHANGELOG.md’s ## [Unreleased] section (plus the commit list and Docker pull commands)
✅ Archive the changelog: the post-release-cleanup.yml workflow then opens a PR that moves ## [Unreleased]’s content into a new dated ## X.Y.Z (YYYY-MM-DD) section and resets ## [Unreleased] back to the empty template - review and merge that PR to close out the release

Step 4: Verify the Release

Check the GitHub Actions workflow:
- Go to: https://github.com/myastroboard/myastroboard/actions
- Verify the “Build and Publish Docker Image” workflow completed successfully

Verify the Docker image:

docker pull myastroboard/myastroboard:0.2.0
docker images | grep myastroboard

Check the GitHub Release:
- Go to: https://github.com/myastroboard/myastroboard/releases
- Verify the new release appears with auto-generated notes

Test the published image:

# Pull and run the new version
docker run --rm myastroboard/myastroboard:0.2.0 cat /app/VERSION

🔄 Rebuilding without a new version

The publish workflow only runs on a v*.*.* tag push; it has no manual trigger. To republish, push a new patch tag (see Hotfix Releases).

📝 Release Notes Best Practices

Release notes are generated automatically from CHANGELOG.md’s ## [Unreleased] section (see Step 1 above) plus the commit list and Docker pull commands - there’s normally nothing to write by hand at release time. The real editing happens before tagging, in the PRs that add their CHANGELOG.md entry: keep each bullet to one or two lines (see CONTRIBUTING.md#changelog), and use the right subsection (### Features, ### Fixes, ### Breaking changes) so it lands in the right place both in CHANGELOG.md and in the generated release notes.

If a release still needs manual editing after creation (a migration note, a known issue found after tagging, contributor shout-outs):

Go to the release page
Click “Edit release”
Add the extra section below what was generated - don’t rewrite the generated Changelog/Commits sections by hand, fix the source in CHANGELOG.md instead (via a follow-up PR) so the archived entry stays correct too

Example addition:

## 📖 Migration Guide
If upgrading from v0.1.x, you need to:
1. Update your docker-compose.yml
2. Run migration script

## 🙏 Contributors
Thanks to @username for their contribution!

🐛 Hotfix Releases

For critical bug fixes that need immediate release:

Create a hotfix branch:

git checkout -b fix/hotfix-0.2.1 v0.2.0

Apply the fix:

# Make your changes
git add .
git commit -m "fix: critical bug in X"

Update VERSION:

echo "0.2.1" > VERSION
git add VERSION
git commit -m "chore: bump version to 0.2.1"

Merge to main:

git checkout main
git merge fix/hotfix-0.2.1
git push origin main

Tag and release:

git tag -a v0.2.1 -m "Hotfix v0.2.1"
git push origin v0.2.1

🔙 Rolling Back a Release

If a release has issues:

Option 1: Delete the Release (Recommended for Early Mistakes)

# Delete the tag locally
git tag -d v0.2.0

# Delete the tag remotely
git push origin :refs/tags/v0.2.0

# Delete the release on GitHub (do this manually via GitHub UI)

Option 2: Create a New Patch Release

If users have already pulled the image, create a fix:

# Fix the issue
echo "0.2.1" > VERSION
git add VERSION
git commit -m "fix: issue in v0.2.0"
git push origin main

# Create new release
git tag -a v0.2.1 -m "Fix for v0.2.0"
git push origin v0.2.1

Ensure the tag follows the v*.*.* format
Check that you pushed the tag: git push origin v0.2.0
Verify GitHub Actions is enabled in repository settings

Docker Build Fails

Check the workflow logs in GitHub Actions
Verify the Dockerfile is valid
Ensure all dependencies are available

Release Not Created

Check that the tag starts with v (e.g., v0.2.0)
Verify the workflow has contents: write permission
Check GitHub Actions logs for errors

Image Not Published

Verify GitHub Packages is enabled
Check repository permissions for GITHUB_TOKEN
Ensure the workflow completed successfully

Last updated 2026-11-13

MyAstroBoard Documentation