A self-hosted media server and file management system
Vue ffmpegfile-serverjellyfinlaravelmediamedia-playermedia-servermediabrowsermediaservermusicmusic-librarymusic-playermusicplayerself-hostedvuejs
Version Management & Release Workflow
This project uses a semantic versioning strategy with automated releases through GitHub Actions.
Branch Strategy
main - Beta Development Branch
- Always holds the next minor version as
X.Y.0-beta.N - Never holds patch versions (always
X.Y.0) - Each push increments the beta counter:
0.16.0-beta.1,0.16.0-beta.2, etc. - To bump the base version (minor or major), use the manual workflow dispatch
- Merging a PR to prod will bump the base version automatically (minor)
prod - Production Branch
- Holds stable production versions:
X.Y.Z - Direct pushes are disabled
- Takes version from file merged into the branch (no bumping happens here)
- Releases are triggered by merging PRs from
mainorrelease/* - Automatically generates changelogs from conventional commits
release/* - Patch Release Branches (WIP)
- Created from
prodor cherry-picked frommainfor patch fixes - Each push increments version and RC counter:
0.16.1-rc.1,0.16.1-rc.2, etc. - Format:
release/0.16.x(thexis just notation, should be used in automation somehow) - Merges to
prodas patch releases
Release Types
Minor Release (from main to prod)
# Current state
prod: 0.15.2
main: 0.16.0-beta.5
# After PR from main → prod
prod: 0.16.0 # Takes version from main
main: 0.17.0-beta.0 # Continues with beta releases from next minor version
Steps:
- Develop features on
main→ auto-tags as0.16.0-beta.N - When ready, create PR from
maintoprod PR validation checks version bump is valid- Merge PR → auto-releases
0.16.0with changelog - Main is bumped to
0.17.0-beta.0
Major Release (from main to prod)
# First, bump major version on main
# Run: Actions → "CI & Docker Release (Beta)" → Run workflow → Select "major"
# Before
main: 0.16.0-beta.5
# After workflow dispatch
main: 1.0.0-beta.0
# Continue development
main: 1.0.0-beta.1, 1.0.0-beta.2, ...
# Create PR main → prod when ready
prod: 1.0.0
Patch Release (from release/* to prod)
WIP
Conventional Commits
All commits should follow the Conventional Commits format for automatic changelog generation:
Format
<type>[optional scope]: <description>
[optional body]
Types
- feat: New feature or addition
- fix: Bug fix
- docs: Documentation changes
- style: Code style changes (linting, etc.)
- refactor: Code refactoring
- perf: Performance improvements
- test: Adding or updating tests
- chore: Maintenance tasks
- build: Build system changes
- ci: CI configuration changes
- revert: Reverting previous commits
Breaking Changes
feat!: redesign user authentication API
BREAKING CHANGE: The authentication endpoint has changed from /auth to /api/v2/auth
Examples
feat: add dark mode support
feat(ui): implement responsive player controls
fix: memory leak in open graph image generator
fix(api): folder name overwritten by title
docs: update readme
perf: eager load users on tasks
refactor(frontend): simplify records api handling
Changelog Generation
Changelogs are automatically generated from conventional commits when merging to prod:
- Features (
feat:) → ✨ Features section - Bug Fixes (
fix:) → 🐛 Bug Fixes section - Performance (
perf:) → ⚡ Performance Improvements section - Breaking Changes (
!:orBREAKING CHANGE) → ⚠️ BREAKING CHANGES section - Refactoring (
refactor:) → ♻️ Code Refactoring section - Documentation (
docs:) → 📝 Documentation section
The changelog is:
- Appended to
CHANGELOG.mdin the repo - Used as the GitHub Release description
- Generated from commits between previous and current release tags
Workflows
1. ci-main.yml - Beta Releases
Triggers:
- Push to
main(excludes VERSION and CHANGELOG.md changes) - Manual workflow dispatch (to bump major/minor version)
Actions:
- Runs tests
- Increments beta counter (or bumps version if manual)
- Creates git tag (e.g.,
0.16.0-beta.5) - Builds and pushes Docker image with
betaand version tags - Creates GitHub pre-release with files if Docker files changed
2. ci-prod.yml - Production Releases
Triggers:
- PR merged to
prodbranch
Actions:
- Runs tests
- Creates production git tag (e.g.,
0.16.0) - Generates changelog from conventional commits
- Updates
CHANGELOG.md - Builds and pushes Docker image with
latestand version tags - Creates GitHub release with changelog and Docker setup packages
3. release-patch.yml - Release Candidate (Patch)
Triggers:
- Push to
release/*branches
Actions:
- WIP
Version File
The VERSION file in the repository root contains the base semantic version:
- On
main:X.Y.0(no beta suffix in file) - On
prod:X.Y.Z(production version) - On
release/*:X.Y.Z(patch version)
Git tags include the full version with suffixes:
- Beta:
X.Y.0-beta.N - RC:
X.Y.Z-rc.N - Production:
X.Y.Z
Docker Tags
From main (Beta)
aminnausin/mediaserver:beta(always latest beta)aminnausin/mediaserver:0.16.0-beta.5(specific beta)
From prod (Production)
aminnausin/mediaserver:latest(always latest stable)aminnausin/mediaserver:0.16.0(specific version)
From release/* (RC)
- No Docker images built for RCs
- Docker images only built when merged to prod
GitHub Releases
Beta Releases (from main)
- Pre-release
- Includes Docker setup packages (if Docker files changed)
- Created automatically on push to main
Production Releases (from prod)
- Includes:
- Auto-generated changelog from conventional commits
- Docker setup packages (Linux and Windows)
- Created automatically on merge to prod
Release Candidates (from release/*)
- No GitHub releases for RCs
- Only git tags created