Release Process

Overview

MQTT Explorer uses an automated release process powered by semantic-release and GitHub Actions. Releases are triggered by pull requests to specific branches and follow semantic versioning.

Release Channels

MQTT Explorer has two release channels:

Production Release

Branch: releaseAudience: All usersStability: Stable, production-readyDistribution: GitHub Releases, website downloads

Beta Release

Branch: betaAudience: Early adopters, testersStability: Feature-complete but may have bugsDistribution: GitHub Releases (pre-release)

Release Workflow

Create a pull request

Open a PR to the target branch:

# For production release
git checkout -b feature/new-feature
git commit -m "feat: add new MQTT topic visualization"
git push origin feature/new-feature
# Create PR to 'release' branch

# For beta release
git checkout -b feature/experimental
git commit -m "feat: add experimental features"
git push origin feature/experimental
# Create PR to 'beta' branch

Ensure conventional commits

Your PR must include at least one commit with a semantic prefix:

feat: - New feature (triggers minor version bump)
fix: - Bug fix (triggers patch version bump)
perf: - Performance improvement (triggers patch)
BREAKING CHANGE: - Breaking change (triggers major bump)

Commits without these prefixes (e.g., docs:, chore:, style:) will not trigger a new release.

Merge the pull request

Once approved and CI passes, merge the PR.

Automated release process

GitHub Actions automatically:

Analyzes commits to determine version bump
Generates changelog from commit messages
Creates a git tag and GitHub release
Builds packages for all platforms
Uploads artifacts to GitHub Releases
Publishes Snap package to Snapcraft Store

Semantic Versioning

Versions follow semver format: MAJOR.MINOR.PATCH

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Examples:

feat: add WebSocket reconnection logic

Implements automatic reconnection with exponential backoff
when WebSocket connection is lost.

Closes #123

Version Bump Rules

Commit Type	Example	Version Change
`feat:`	New feature	`0.4.0` → `0.5.0`
`fix:`	Bug fix	`0.4.0` → `0.4.1`
`perf:`	Performance	`0.4.0` → `0.4.1`
`BREAKING CHANGE:`	Breaking API	`0.4.0` → `1.0.0`
`docs:`, `chore:`, `style:`	No functional change	No release

GitHub Actions Workflow

The release process is defined in .github/workflows/platform-builds.yml:

name: Build

on:
  push:
    branches:
      - release
      - beta

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: false

jobs:
  build:
    strategy:
      matrix:
        build:
          - os: ubuntu-latest
            task: linux
          - os: windows-latest
            task: win
          - os: macos-latest
            task: mac
    runs-on: ${{ matrix.build.os }}

Build Steps

Semantic Release

Determines if a new release should be created:

- name: Semantic Release
  uses: cycjimmy/semantic-release-action@v4
  id: semantic
  env:
    GITHUB_TOKEN: ${{ steps.create_token.outputs.token }}

Output: steps.semantic.outputs.new_release_published is 'true' if release is triggered.

Build Application

Compiles TypeScript and bundles React app:

- run: yarn build
  if: steps.semantic.outputs.new_release_published == 'true'

Prepare Clean Release

Creates isolated build environment:

- run: yarn prepare-release
  if: steps.semantic.outputs.new_release_published == 'true'

Package for Platform

Creates platform-specific installers:

- run: yarn package ${{ matrix.build.task }}
  if: steps.semantic.outputs.new_release_published == 'true'
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    SNAPCRAFT_STORE_CREDENTIALS: ${{ secrets.SNAPCRAFT_STORE_CREDENTIALS }}
    APPLE_ID: ${{ secrets.APPLE_ID }}
    APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
    APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}

Release Assets

Each release includes:

Windows

MQTT Explorer Setup [version].exe - NSIS installer
MQTT Explorer [version].exe - Portable executable

macOS

MQTT Explorer-[version].dmg - Intel disk image
MQTT Explorer-[version]-arm64.dmg - Apple Silicon disk image

Linux

MQTT-Explorer-[version].AppImage - x64 portable
MQTT-Explorer-[version]-arm64.AppImage - ARM64 portable
MQTT-Explorer-[version]-armv7l.AppImage - ARM portable
mqtt-explorer_[version]_amd64.deb - Debian package
mqtt-explorer_[version]_arm64.deb - Debian ARM64
mqtt-explorer_[version]_armhf.deb - Debian ARM
mqtt-explorer_[version]_amd64.snap - Snap package (also on Snapcraft Store)

Additional Files

CHANGELOG.md - Generated release notes
latest.yml / latest-mac.yml - Auto-update metadata

Semantic Release Configuration

Configured via .releaserc or package.json:

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/github",
    [
      "@semantic-release/git",
      {
        "assets": ["package.json", "CHANGELOG.md"],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  ]
}

Plugin Responsibilities

Plugin	Purpose
`commit-analyzer`	Determines version bump from commits
`release-notes-generator`	Creates changelog from commits
`changelog`	Updates `CHANGELOG.md` file
`npm`	Updates `version` in `package.json`
`github`	Creates GitHub release with assets
`git`	Commits version bump back to repository

Auto-Update System

Electron apps support automatic updates via electron-updater.

Update Metadata

electron-builder generates update manifests: macOS: latest-mac.yml

version: 0.4.0-beta.5
files:
  - url: MQTT-Explorer-0.4.0-beta.5.dmg
    sha512: abc123...
    size: 87654321
path: MQTT-Explorer-0.4.0-beta.5.dmg
sha512: abc123...
releaseDate: '2024-03-05T10:30:00.000Z'

Windows: latest.yml

version: 0.4.0-beta.5
files:
  - url: MQTT-Explorer-Setup-0.4.0-beta.5.exe
    sha512: def456...
    size: 65432100
path: MQTT-Explorer-Setup-0.4.0-beta.5.exe
sha512: def456...
releaseDate: '2024-03-05T10:30:00.000Z'

Update Check Frequency

Configured in the Electron main process:

import { autoUpdater } from 'electron-updater'

// Check for updates on startup
autoUpdater.checkForUpdatesAndNotify()

// Check every 4 hours
setInterval(() => {
  autoUpdater.checkForUpdatesAndNotify()
}, 4 * 60 * 60 * 1000)

Linux AppImages and browser mode do not support auto-update. Users must manually download new versions.

Manual Release (Emergency)

If automated release fails, create a release manually:

Determine version

# Current version
cat package.json | grep version

# Bump version
npm version patch  # or minor, major

Create git tag

git tag v0.4.1
git push origin v0.4.1

Build packages locally

yarn build
yarn prepare-release
yarn package mac
yarn package linux
yarn package win

Create GitHub release

Go to https://github.com/thomasnordquist/MQTT-Explorer/releases/new
Select the tag you created
Generate release notes from commits
Upload packages from build/ directory
Publish release

Manual releases skip semantic versioning validation. Ensure version numbers follow semver conventions.

Rollback a Release

If a release has critical bugs:

Delete the GitHub release

Go to the release page and click “Delete release”.

Delete the git tag

git tag -d v0.4.1
git push origin :refs/tags/v0.4.1

Fix the issue

Create a new PR with the fix.

Create new release

Merge the fix PR to trigger a new release with a patch bump.

Docker Releases

Browser mode Docker images are built separately in .github/workflows/docker-browser.yml: Triggers:

Push to master, beta, or release branches
Schedule: Every two weeks (1st and 15th at 2:00 AM UTC)
Manual trigger

Tags:

latest - Latest master build
master, beta, release - Branch-specific tags
<branch>-<sha> - Commit-specific tags

Registry: ghcr.io/thomasnordquist/mqtt-explorer

# Pull latest release
docker pull ghcr.io/thomasnordquist/mqtt-explorer:latest

# Pull beta
docker pull ghcr.io/thomasnordquist/mqtt-explorer:beta

# Pull specific commit
docker pull ghcr.io/thomasnordquist/mqtt-explorer:master-abc1234

Troubleshooting

No Release Created

Missing feat: or fix: commits

Ensure your PR includes commits with semantic prefixes:

git log --oneline
# Should show: feat: or fix: commits

semantic-release failed

Check GitHub Actions logs for errors:

Run cycjimmy/semantic-release-action@v4
[semantic-release] › ✔  Analyzing commits
[semantic-release] › ✖  No release published

Common causes:

Only docs: or chore: commits
No changes since last release

ReleaseBot token expired

The workflow uses a GitHub App token for releases:

- id: create_token
  uses: actions/create-github-app-token@v1
  with:
    app-id: ${{ secrets.RELEASE_BOT_APP_ID }}
    private-key: ${{ secrets.RELEASE_BOT_PRIVATE_KEY }}

Verify app credentials are valid.

Package Upload Failed

GitHub rate limit: Wait and re-run the workflow Asset already exists: Delete the release and re-run Snapcraft authentication: Re-export credentials:

snapcraft export-login snapcraft.login

Notarization Failed (macOS)

See Notarization Troubleshooting for detailed steps.

Best Practices

Write good commit messages

Clear, descriptive commits generate better changelogs:

# Good
feat: add JSON payload formatting

# Bad
feat: stuff

Test before merging

Run full test suite locally:

yarn test:all

Use beta for experiments

Release experimental features to beta first:

# Merge to beta for testing
# Merge to release when stable

Monitor release success

Watch GitHub Actions logs during releases to catch issues early.

Next Steps

Building

Learn how to build MQTT Explorer from source

Notarization

Set up macOS notarization for secure distribution

Contributing

Deployment

Overview

Release Channels

Production Release

Beta Release

Release Workflow

Semantic Versioning

Commit Message Format

Version Bump Rules

GitHub Actions Workflow

Build Steps

Release Assets

Windows

macOS

Linux

Additional Files

Semantic Release Configuration

Plugin Responsibilities

Auto-Update System

Update Metadata

Update Check Frequency

Manual Release (Emergency)

Rollback a Release

Docker Releases

Troubleshooting

No Release Created

Package Upload Failed

Notarization Failed (macOS)

Best Practices

Write good commit messages

Test before merging

Use beta for experiments

Monitor release success

Next Steps

Building

Notarization

Build docs developers (and LLMs) love

Contributing

Deployment

​Overview

​Release Channels

Production Release

Beta Release

​Release Workflow

​Semantic Versioning

​Commit Message Format

​Version Bump Rules

​GitHub Actions Workflow

​Build Steps

​Release Assets

​Windows

​macOS

​Linux

​Additional Files

​Semantic Release Configuration

​Plugin Responsibilities

​Auto-Update System

​Update Metadata

​Update Check Frequency

​Manual Release (Emergency)

​Rollback a Release

​Docker Releases

​Troubleshooting

​No Release Created

​Package Upload Failed

​Notarization Failed (macOS)

​Best Practices

Write good commit messages

Test before merging

Use beta for experiments

Monitor release success

​Next Steps

Building

Notarization

Build docs developers (and LLMs) love

Overview

Release Channels

Release Workflow

Semantic Versioning

Commit Message Format

Version Bump Rules

GitHub Actions Workflow

Build Steps

Release Assets

Windows

macOS

Linux

Additional Files

Semantic Release Configuration

Plugin Responsibilities

Auto-Update System

Update Metadata

Update Check Frequency

Manual Release (Emergency)

Rollback a Release

Docker Releases

Troubleshooting

No Release Created

Package Upload Failed

Notarization Failed (macOS)

Best Practices

Next Steps