mirror of
https://github.com/Dvorinka/swingmusic-extended.git
synced 2026-06-03 20:13:02 +00:00
Tomas Dvorak
179 lines
5.0 KiB
Markdown
179 lines
5.0 KiB
Markdown
# 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 any branch
|
|
- Pull requests from any branch
|
|
- 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. 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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
|