Mue Release Process

This document outlines the complete release process for Mue maintainers.

📋 Table of Contents

Overview
Version Numbering
Pre-Release Checklist
Beta Release Process
Production Release Process
Hotfix Release Process
Post-Release Tasks
Store Submission
Troubleshooting

Overview

Mue uses a three-branch release workflow:

dev → beta → main

dev: Active development and feature integration
beta: Release candidates for community testing
main: Production-ready stable releases

Version Numbering

We follow Semantic Versioning: MAJOR.MINOR.PATCH

When to Bump

Type	When	Example
Major (x.0.0)	Breaking changes, API changes, major UI overhaul	7.5.0 → 8.0.0
Minor (0.x.0)	New features, backward-compatible changes	7.5.0 → 7.6.0
Patch (0.0.x)	Bug fixes, small improvements	7.5.0 → 7.5.1

Beta Versions

Beta versions follow the format: MAJOR.MINOR.PATCH-beta.X

Example: 7.6.0-beta.1, 7.6.0-beta.2

Pre-Release Checklist

Before starting any release:

All intended features/fixes are merged to dev
No critical bugs in issue tracker
dev branch builds successfully
All CI checks passing
Translation updates synced from Weblate (if applicable)
Breaking changes documented

Beta Release Process

Step 1: Version Bump

Go to Actions → Version Bump → Run workflow
Configure:
- Branch: dev
- Bump type: Choose patch, minor, or major
- Pre-release: Select beta
Click Run workflow
Workflow will:
- Calculate new version (e.g., 7.6.0-beta.1)
- Update all 6 version files
- Create git tag
- Push to dev

Step 2: Create Beta PR

Go to Pull Requests → New pull request
Configure:
- Base: beta
- Compare: dev
Fill in PR template:
- Add changelog preview
- List major changes
- Add testing notes
Get 2 maintainer approvals

Step 3: Merge and Release

Merge PR to beta branch
Beta Release Workflow auto-triggers:
- Builds extension for all browsers
- Creates GitHub pre-release
- Uploads Chrome/Firefox ZIPs
- Generates changelog
Verify release:
- Check Releases page
- Download and test ZIPs
- Verify version numbers

Step 4: Beta Testing

Share with testers:
- Post release link in Discord/testing channel
- Include installation instructions
- Provide feedback form/issue template
Monitor feedback:
- Track issues tagged with beta version
- Prioritize critical bugs
- Document all feedback
Fix issues:
- Fix bugs on dev branch
- Create new beta (repeat from Step 1)
- Increment beta number (7.6.0-beta.2, etc.)
Minimum beta period: 3-7 days (depending on changes)
Stability criteria:
- No P0/P1 bugs reported
- Positive feedback from 5+ testers
- All critical features tested

Production Release Process

Step 1: Pre-Production Checks

Beta has been stable for minimum period
All critical beta bugs resolved
Release notes prepared
Store credentials verified
Team notified of pending release

Step 2: Version Bump to Stable

Go to Actions → Version Bump → Run workflow
Configure:
- Branch: beta
- Bump type: Usually same as beta (minor/major/patch)
- Pre-release: Leave empty (stable release)
This updates 7.6.0-beta.X → 7.6.0

Step 3: Create Production PR

Go to Pull Requests → New pull request
Configure:
- Base: main
- Compare: beta
Fill in release PR checklist:
- Beta tested for X days
- All critical bugs resolved
- 5+ beta testers approved
- Release notes prepared
- Store submission ready
- Changelog updated on website
Get 2 maintainer approvals

Step 4: Merge and Release

Merge PR to main
Production Release Workflow starts:
- Builds extension
- Creates production tag
- Generates full changelog
- Creates GitHub release
- Pauses for manual approval
Review in GitHub:
- Go to Actions → Production Release → running workflow
- Review release notes
- Check build artifacts
- Approve deployment in Environments → production
Wait 10 minutes (cooldown period)
Release completes:
- GitHub release published
- ZIPs uploaded
- Tag created

Step 5: Store Submission

Manual submission required (for now):

Go to Actions → Submit → Run workflow
Enter version tag: 7.6.0 (no 'v' prefix)
Click Run workflow
Monitor submission workflow:
- Chrome Web Store submission
- Firefox Add-ons submission
- Edge Add-ons submission
Verify store listings:
Store review times:
- Chrome: 1-3 days
- Edge: 1-2 days
- Firefox: hours to days

Step 6: Sync Branches

After production release, sync version to other branches:

# Update dev and beta with main
git checkout dev
git pull origin dev
git merge main
git push origin dev

git checkout beta
git pull origin beta
git merge main
git push origin beta

Hotfix Release Process

When to Use Hotfix

Only for critical production bugs:

Security vulnerabilities
Data loss bugs
Extension completely broken
Critical functionality broken for all users

Process

Create hotfix branch from main:

git checkout main
git pull origin main
git checkout -b hotfix/brief-description

Fix the bug:
- Make minimal changes (hotfix only)
- Test thoroughly
- Commit with conventional format

Push branch:

git push origin hotfix/brief-description

Run hotfix workflow:
- Go to Actions → Hotfix Release → Run workflow
- Description: Brief bug description
- Branch name: hotfix/brief-description
- Click Run workflow
Approve deployment:
- Workflow pauses for approval
- Review changes carefully
- Approve in Environments → production
Workflow automatically:
- Bumps patch version (7.6.0 → 7.6.1)
- Merges to main
- Creates release tag
- Builds and releases
- Back-merges to beta and dev
Submit to stores immediately:
- Go to Actions → Submit → Run workflow
- Enter new version (e.g., 7.6.1)
Notify users:
- Post urgent update notice
- Update website changelog
- Notify via social media if critical

Clean up:

git push origin --delete hotfix/brief-description

Post-Release Tasks

After any production release:

Immediate (within 24 hours)

Verify store submissions completed
Update https://muetab.com/blog/changelog
Announce on Discord/social media
Monitor issue tracker for new reports
Verify demo site (demo.muetab.com) is updated

Within 1 Week

Review analytics for adoption rate
Address any quick-fix bugs as patch release
Update roadmap/milestones
Thank beta testers and contributors

Ongoing

Monitor store reviews/ratings
Respond to user feedback
Plan next release cycle

Store Submission

Required Credentials

Stored in GitHub Secrets as SUBMIT_KEYS:

{
  "chrome": {
    "extId": "bngmbednanpcfochchhgbkookpiaiaid",
    "clientId": "...",
    "clientSecret": "...",
    "refreshToken": "..."
  },
  "firefox": {
    "extId": "{ac143a20-4b61-4c81-abdd-4bff77032972}",
    "jwtIssuer": "...",
    "jwtSecret": "..."
  },
  "edge": {
    "productId": "...",
    "clientId": "...",
    "clientSecret": "...",
    "accessTokenUrl": "..."
  }
}

Beta Distribution

Chrome/Edge Beta:

Use unlisted listing (share link with testers)
Or use trusted testers group (max 1000)

Firefox Beta:

Upload as unlisted to AMO
Share download link from GitHub Releases

Safari Beta:

Currently manual sideload from GitHub Releases

Troubleshooting

Build Fails

Issue: Build fails in workflow

Solutions:

Check CI logs for specific error
Run bun run build locally to reproduce
Ensure all dependencies installed
Check for linting errors: bun run lint

Version Mismatch

Issue: Version numbers don't match across files

Solutions:

Re-run Version Bump workflow
Manually verify all 6 files:
- package.json
- manifest/chrome.json
- manifest/firefox.json
- safari/Mue Extension/Resources/manifest.json
- safari/Mue.xcodeproj/project.pbxproj
- src/config/constants.js

Tag Already Exists

Issue: Git tag already exists for version

Solutions:

Delete existing tag:

git tag -d v7.6.0
git push origin :refs/tags/v7.6.0

Re-run workflow

Store Submission Fails

Issue: PlasmoHQ BPP submission fails

Solutions:

Check workflow logs for specific error
Verify credentials in SUBMIT_KEYS secret
Check store developer console for issues
Try manual submission as fallback

Merge Conflicts

Issue: Conflicts when merging beta → main

Solutions:

Update beta with main first:

git checkout beta
git merge main
git push origin beta

Create new PR from beta → main

Emergency Rollback

If a production release has critical bugs:

Option 1: Hotfix (Preferred)

Follow Hotfix Process to quickly patch and release.

Option 2: Store Rollback

Each store allows rolling back to previous version:

Chrome Web Store:

Go to Developer Dashboard
Select Mue extension
Package → Select previous version
Publish

Firefox Add-ons:

Go to Developer Hub
Select Mue add-on
Manage Status & Versions
Enable previous version

Edge Add-ons:

Go to Partner Center
Select Mue extension
Packages → Restore previous

Option 3: Revert and Re-release

git checkout main
git revert <commit-hash>
git push origin main

Then follow production release process.

Questions?

Contact maintainers:

@davidcralph
@alexsparkes

Or open a discussion: https://github.com/mue/mue/discussions

FilesExpand file tree

RELEASE_PROCESS.md

Latest commit

History

RELEASE_PROCESS.md

File metadata and controls

Mue Release Process

📋 Table of Contents

Overview

Version Numbering

When to Bump

Beta Versions

Pre-Release Checklist

Beta Release Process

Step 1: Version Bump

Step 2: Create Beta PR

Step 3: Merge and Release

Step 4: Beta Testing

Production Release Process

Step 1: Pre-Production Checks

Step 2: Version Bump to Stable

Step 3: Create Production PR

Step 4: Merge and Release

Step 5: Store Submission

Step 6: Sync Branches

Hotfix Release Process

When to Use Hotfix

Process

Post-Release Tasks

Immediate (within 24 hours)

Within 1 Week

Ongoing

Store Submission

Required Credentials

Beta Distribution

Troubleshooting

Build Fails

Version Mismatch

Tag Already Exists

Store Submission Fails

Merge Conflicts

Emergency Rollback

Option 1: Hotfix (Preferred)

Option 2: Store Rollback

Option 3: Revert and Re-release

Questions?