Skip to main content

Release Process

This guide explains how to create a new firmware release for the MyStation project.

Overview​

The release process follows these steps:

Prerequisites​

Before creating a release, ensure:

  • All features for this release are merged to main branch
  • All tests pass locally (pio test -e native)
  • The firmware builds successfully (pio run)
  • You have reviewed the changes since the last release

Step 1: Create a Git Tag​

Version Format​

The project follows Semantic Versioning with a v prefix:

v<MAJOR>.<MINOR>.<PATCH>
Version PartWhen to IncrementExample
MAJORBreaking changes or major new featuresv1.0.0 → v2.0.0
MINORNew features, backward compatiblev1.0.0 → v1.1.0
PATCHBug fixes, backward compatiblev1.0.0 → v1.0.1

Examples​

v1.0.0    # Initial stable release
v1.0.1    # Bug fix release
v1.1.0    # New feature release
v2.0.0    # Major release with breaking changes
v1.2.0-beta.1  # Pre-release (optional)

Create the Tag​

  1. Ensure you're on the latest main branch:

    git checkout main
    git pull origin main

  2. Check the current version:

    git describe --tags --abbrev=0
    # Output: v1.0.0 (example)

  3. Create an annotated tag:

    # For a patch release (bug fixes)
    git tag -a v1.0.1 -m "Release v1.0.1: Bug fixes and improvements"

    # For a minor release (new features)
    git tag -a v1.1.0 -m "Release v1.1.0: Add new display mode"

    # For a major release (breaking changes)
    git tag -a v2.0.0 -m "Release v2.0.0: Major architecture update"

    Note: Use annotated tags (-a) instead of lightweight tags. Annotated tags store extra metadata including the tagger name, email, date, and message.

  4. Verify the tag was created:

    git tag -l "v*" --sort=-v:refname | head -5

Step 2: Push the Tag to GitHub​

Push the tag to trigger the GitHub Actions workflow:

git push origin v1.0.1

Or push all tags:

git push origin --tags

Important: Only push the tag when you're ready to create a release. Once pushed, the GitHub Actions workflow will start automatically.

Step 3: Monitor the GitHub Actions Workflow​

  1. Go to the repository on GitHub
  2. Navigate to Actions tab
  3. Find the workflow run triggered by your tag push
  4. Monitor the build progress:
    • Build job: Compiles firmware and runs tests
    • Release job: Creates the draft release (only runs if build succeeds)

If the Build Fails​

  1. Check the workflow logs for errors
  2. Fix the issues in a new commit
  3. Delete the failed tag: 
    # Delete local tag
    git tag -d v1.0.1

    # Delete remote tag
    git push origin :refs/tags/v1.0.1
  4. Delete the draft release on GitHub (if created)
  5. Start over from Step 1

Step 4: Review the Draft Release​

Once the GitHub Actions workflow completes successfully, a draft release is created.

  1. Go to the repository on GitHub
  2. Navigate to Releases (right sidebar or Code → Releases)
  3. Find the draft release (marked with "Draft" label)

What to Review​

  • Release title: Should be MyStation v1.0.1
  • Release notes: Auto-generated from commit messages
  • Attached files:
    • firmware.bin - Main firmware binary
    • bootloader.bin - ESP32 bootloader
    • partitions.bin - Partition table
    • firmware.elf - Debug symbols
    • build_info.txt - Build metadata
    • config_my_station.html - Configuration page
    • VERSION.txt - Version information
    • mystation-firmware-{sha}.zip - Complete package

Edit Release Notes (Optional)​

Click Edit on the draft release to:

  • Add a summary of changes
  • Highlight breaking changes
  • Add upgrade instructions
  • Include known issues
  • Add acknowledgments

Recommended Release Notes Template:

## What's Changed

### New Features

- Feature 1 description
- Feature 2 description

### Bug Fixes

- Fix 1 description
- Fix 2 description

### Breaking Changes

- Change 1 (if any)

## Upgrade Instructions

1. Download `firmware.bin`
2. Flash using web interface or USB

## Full Changelog

https://github.com/gogo-boot/mystation/compare/v1.0.0...v1.0.1

Step 5: Publish the Release​

After reviewing the draft release:

  1. Click Edit on the draft release (if not already editing)
  2. Scroll to the bottom
  3. Ensure Set as the latest release is checked
  4. Click Publish release

The release is now public and will be:

  • Listed on the Releases page
  • Available for OTA updates (devices check the latest release)
  • Visible to users and contributors

Quick Reference​

Command Summary​

# Check current version
git describe --tags --abbrev=0

# Create new tag
git tag -a v1.0.1 -m "Release v1.0.1: Description"

# Push tag to trigger release
git push origin v1.0.1

# Delete tag (if needed)
git tag -d v1.0.1                    # local
git push origin :refs/tags/v1.0.1   # remote

Release Checklist​

  • All changes merged to main
  • Tests pass locally
  • Version number follows semver
  • Tag created with -a flag and descriptive message
  • Tag pushed to GitHub
  • GitHub Actions build successful
  • Draft release reviewed
  • Release notes edited (if needed)
  • Release published

Troubleshooting​

Tag Already Exists​

If you accidentally created a tag with the wrong name:

# Delete and recreate
git tag -d v1.0.1
git tag -a v1.0.1 -m "Correct message"

Workflow Not Triggered​

Ensure your tag follows the v* pattern:

  • ✅ v1.0.0, v1.0.1, v2.0.0-beta.1
  • ❌ 1.0.0, release-1.0.0, V1.0.0

Draft Release Not Created​

Check if the build job failed. The release job only runs after a successful build and only for tag pushes (not for PRs or branch pushes).