swingmusic-extended/.github/CI-README.md

SwingMusic Extended - Unified CI/CD System

Overview

This repository uses a unified CI/CD system that builds all components from the main repository. The main repository (swingmusic-extended) contains submodules for each component:

• Backend: Python server (in src/)
• Web Client: Vue.js frontend (submodule swingmusic-webclient)
• Desktop App: Tauri desktop app (submodule swingmusic-desktop)
• Android App: Android app (submodule swingmusic-android)

Workflows

1. Unified Build (unified-build.yml)

This is the main workflow that builds all components. It runs on:

• Push to main/master/develop branches
• Pull requests to main/master/develop
• Tags (for releases)
• Manual dispatch

Features:

• Smart change detection: Only builds components that changed
• Parallel builds: All components build simultaneously when possible
• Cross-platform builds: Desktop app builds for Linux, Windows, and macOS
• Docker integration: Creates Docker image with backend + web client
• Release automation: Automatic releases on tags

Build Process:

1. Initializes and updates all submodules
2. Detects which components changed
3. Builds only what's needed (or everything on main/tags)
4. Creates artifacts for each component
5. Builds Docker image with backend + web client
6. Creates GitHub release (on tags)

2. Component Tests (component-tests.yml)

Lightweight testing workflow for development. Runs on:

• Push to develop branch
• Pull requests
• Manual dispatch

Purpose:

• Quick feedback during development
• Tests individual components without full builds
• Runs linting, unit tests, and basic build checks

3. Backend and Docker Build (build-and-deploy.yml)

Simplified backup workflow focused only on:

• Backend Python package building
• Docker image creation

4. Desktop CI (desktop-ci.yml)

Legacy desktop-specific workflow (kept for compatibility).

Usage

Automatic Builds

• Development: Push to develop → Component tests run
• Main branch: Push to main/master → Full unified build
• Release: Create tag v* → Full build + release

Manual Builds

You can trigger builds manually with parameters:

1. Go to Actions → Unified Build → "Run workflow"
2. Choose components to build (comma-separated):
   • webclient,desktop,android,backend (default: all)
   • webclient,backend (just web and backend)
   • desktop (just desktop app)

Smart Change Detection

The unified workflow automatically detects changes:

• Files in swingmusic-webclient/ → Builds web client
• Files in swingmusic-desktop/ → Builds desktop app
• Files in swingmusic-android/ → Builds Android app
• Files in src/ → Builds backend
• No changes → Skips unchanged components (except on main/tags)

Artifacts and Releases

Build Artifacts

Each component produces artifacts:

• Web Client: Built frontend files
• Desktop Apps: Platform-specific installers
• Android App: APK files
• Backend: Python wheels

Docker Images

Built images are pushed to GitHub Container Registry:

• ghcr.io/Dvorinka/swingmusic-extended:main-123
• ghcr.io/Dvorinka/swingmusic-extended:latest
• ghcr.io/Dvorinka/swingmusic-extended:v1.0.0

Releases

On tags, automatic releases include:

• Docker image information
• Download links for all components
• Installation instructions
• Auto-generated changelog

Repository Structure

swingmusic-extended/
├── .github/workflows/          # CI/CD workflows
├── src/                        # Backend Python code
├── swingmusic-webclient/       # Submodule: Web frontend
├── swingmusic-desktop/         # Submodule: Desktop app
├── swingmusic-android/         # Submodule: Android app
├── Dockerfile                  # Docker configuration
└── .gitmodules                 # Submodule configuration

Development Workflow

Making Changes

1. Backend changes: Edit files in src/
2. Web client changes:
   • Navigate to swingmusic-webclient/
   • Make changes
   • Commit and push in that submodule
   • Update submodule reference in main repo
3. Desktop changes: Same process in swingmusic-desktop/
4. Android changes: Same process in swingmusic-android/

Updating Submodules

After making changes in a submodule:

# In the submodule directory
cd swingmusic-webclient
git add .
git commit -m "Update web client"
git push

# Back in main repository
cd ..
git add swingmusic-webclient
git commit -m "Update webclient submodule"
git push

Testing Changes

• Small changes: Push to develop for quick component tests
• Full integration: Push to main for complete build
• Release: Create tag for production release

Troubleshooting

Submodule Issues

If builds fail due to submodule issues:

git submodule update --init --recursive
git submodule sync --recursive

Build Failures

Check the Actions tab for detailed logs. Common issues:

• Missing dependencies in submodules
• Outdated submodule references
• Build tool version mismatches

Manual Intervention

You can always:

• Run workflows manually with specific components
• Re-run failed jobs
• Download and test artifacts manually