From 8983da5b1824ed97a875f3532fe0704f021f8111 Mon Sep 17 00:00:00 2001 From: Broque Thomas <26755000+Nezreka@users.noreply.github.com> Date: Tue, 21 Apr 2026 14:40:24 -0700 Subject: [PATCH] Document dev/nightly release channels and contributor workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a Release Channels section to the main README explaining the three Docker image tracks users can choose from: stable :latest (Docker Hub), nightly :dev (GHCR, rebuilt from dev branch), and pinned version tags. Includes a decision table for picking the right channel and switching instructions for docker-compose users. Notes on the Unraid section that the template points at :latest by default, and how to switch an Unraid container to the :dev channel by editing the Repository field. Adds a Contributing section covering the dev → main PR workflow, how to branch off dev, expectations around ruff + pytest passing locally, and how to run the dev gunicorn config. Mirrors a short release-channels blurb at the top of Support/README-Docker.md pointing at the main README's full guide. --- README.md | 75 ++++++++++++++++++++++++++++++++++++++++ Support/README-Docker.md | 10 ++++++ 2 files changed, 85 insertions(+) diff --git a/README.md b/README.md index 6d1c30c9..a3ab2e91 100644 --- a/README.md +++ b/README.md @@ -213,6 +213,43 @@ docker-compose up -d # Access at http://localhost:8008 ``` +### Release Channels + +SoulSync publishes two Docker image tracks so you can choose your level of stability. + +**Stable — `:latest`** (recommended for most users). Hand-promoted from the `dev` branch to `main` when a batch of changes is ready for release. Published to Docker Hub. Your `docker-compose.yml` pulls this by default — no changes needed. + +```bash +docker pull boulderbadgedad/soulsync:latest +``` + +**Nightly — `:dev`**. Rebuilt every night from the `dev` branch (and on every push to dev). Published to GitHub Container Registry. Gets new features and bug fixes before they reach `:latest`, at the cost of occasional instability as changes settle. Good for early adopters, contributors validating their own merges, and anyone helping shake out bugs on Discord before a stable release. + +To switch, edit `docker-compose.yml`: + +```yaml +image: ghcr.io/nezreka/soulsync:dev +``` + +Then run `docker-compose pull && docker-compose up -d`. + +Pinned dev builds are also published as `ghcr.io/nezreka/soulsync:dev-YYYYMMDD-` if you want to stick with an exact known-good snapshot. + +**Version-tagged releases** (e.g. `:2.3`, `:2.4`) are permanent tags published on both registries when a stable release is promoted: + +```bash +docker pull boulderbadgedad/soulsync:2.4 +# or +docker pull ghcr.io/nezreka/soulsync:2.4 +``` + +| You are... | Use | +|---|---| +| A typical user who wants things to work | `:latest` | +| Pinning to a specific version for stability | `:2.3`, `:2.4`, etc. | +| An early adopter who wants new features early and is OK reporting bugs | `:dev` | +| A contributor testing post-merge behavior | `:dev` or a pinned dev build | + ### Unraid SoulSync is available as an Unraid template. Install from Community Applications or manually add the template from: @@ -222,6 +259,8 @@ https://raw.githubusercontent.com/Nezreka/SoulSync/main/templates/soulsync.xml PUID/PGID are exposed in the template — set them to match your Unraid permissions (default: 99/100 for nobody/users). +The template points at `boulderbadgedad/soulsync:latest` (stable) by default. To use the nightly `:dev` channel on Unraid, edit the container's **Repository** field to `ghcr.io/nezreka/soulsync:dev` after installing from the template. + ### Python (No Docker) ```bash @@ -343,3 +382,39 @@ Open SoulSync at `http://localhost:8008` and go to Settings. - **Album Consistency** — pre-flight MusicBrainz release lookup before album downloads - **Automation Engine** — event-driven workflows with signal chains and pipeline deployment - **SoulID System** — deterministic cross-instance artist/album/track identifiers via track-verified API lookup + +--- + +## Contributing + +### Branch workflow + +SoulSync uses a `dev` → `main` flow: + +- **`main`** — release branch. `:latest` images auto-build from this. Only receives merges from `dev`. +- **`dev`** — integration branch. Nightly `:dev` images build from here. PRs land here first for validation before being promoted to `main`. +- **Feature branches** — branched from `dev`. PRs target `dev`. + +### Opening a PR + +1. Fork and clone the repo +2. Branch off `dev`: `git checkout -b fix/your-change dev` +3. Make your changes and commit +4. Push and open a PR against **`dev`** (not `main`) +5. CI (`build-and-test.yml`) runs ruff lint + compile + pytest on your branch — wait for green +6. A maintainer reviews and merges + +### Running locally + +```bash +pip install -r requirements-dev.txt +python -m ruff check . # must be 0 errors +python -m pytest # all tests must pass +gunicorn -c gunicorn.dev.conf.py wsgi:application +``` + +Ruff config lives in `pyproject.toml`. The ruleset is intentionally lenient — it catches real bugs (undefined names, import shadowing, closure-in-loop) without style nits. + +### Reporting bugs / requesting features + +Open an issue on GitHub. For user-side support, the Discord community is the fastest place to ask. diff --git a/Support/README-Docker.md b/Support/README-Docker.md index 77d0f2d8..ce4a9c54 100644 --- a/Support/README-Docker.md +++ b/Support/README-Docker.md @@ -1,5 +1,15 @@ # SoulSync WebUI - Docker Deployment Guide +## Release Channels + +SoulSync publishes two Docker image tracks: + +- **Stable — `boulderbadgedad/soulsync:latest`** (Docker Hub). Hand-promoted from the `dev` branch when a batch of changes is ready. Default in `docker-compose.yml`. +- **Nightly — `ghcr.io/nezreka/soulsync:dev`** (GHCR). Rebuilt every night and on every push to `dev`. Faster access to new features at the cost of occasional instability. +- **Version-tagged — `:2.3`, `:2.4`, etc.** on both registries for pinning to a specific release. + +To switch a running install to the nightly channel, edit the `image:` line in `docker-compose.yml` to `ghcr.io/nezreka/soulsync:dev` and run `docker-compose pull && docker-compose up -d`. See the [main README](../README.md#release-channels) for the full channel guide. + ## 🐳 Quick Start ### Prerequisites