chore(ci): publish latest from main and retire the edge tag (#711)

* fix(docs): update versioning strategy and tag policies for Docker images

* fix(docs): clarify versioning strategy in environment configuration
fix(docker): update docker-push script to remove local latest tag handling

* fix(docs): clarify VERSION variable usage in Docker push script

docker/docker-push.sh

@@ -8,16 +8,13 @@ set -e  # Exit on error
 
 # Configuration
 DOCKERHUB_USERNAME="${DOCKERHUB_USERNAME:-classroomio}"  # Change this to your Docker Hub username
-VERSION="${VERSION:-latest}"  # Can be overridden with VERSION env var
+VERSION="${VERSION:?set VERSION to the tag to publish, e.g. VERSION=1.4.2 — this script never pushes :latest (CI owns latest from main)}"
 PUBLIC_IS_SELFHOSTED="${PUBLIC_IS_SELFHOSTED:-true}"
 PLATFORMS="${PLATFORMS:-linux/amd64,linux/arm64}"
 
-# Only a real semver release should also move the `latest` tag — building edge/main/dev
-# must NOT clobber the stable `latest` pointer (mirrors docker-publish.yml's tag policy).
-# Use `if` (not `&&`) so the function always returns 0 even when it emits no tag — a helper
-# returning non-zero inside a $(...) argument is fragile under `set -e` / inherit_errexit.
-is_release_version() { [[ "${VERSION}" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+$ ]]; }
-latest_arg() { if is_release_version; then printf -- '-t %s:latest' "$1"; fi; }
+# This manual/local helper pushes ONLY the explicit ${VERSION} tag. `latest` is published
+# exclusively by CI from `main` (see .github/workflows/docker-publish.yml) — to move `latest`,
+# merge to main or re-run that workflow, never this script.
 
 # Colors for output
 GREEN='\033[0;32m'
@@ -46,7 +43,6 @@ docker buildx build \
     --platform "${PLATFORMS}" \
     -f docker/Dockerfile.api \
     -t ${DOCKERHUB_USERNAME}/api:${VERSION} \
-    $(latest_arg ${DOCKERHUB_USERNAME}/api) \
     --push \
     .
 echo -e "${GREEN}✓ API image published successfully!${NC}"
@@ -60,7 +56,6 @@ docker buildx build \
     -f docker/Dockerfile.dashboard \
     --build-arg PUBLIC_IS_SELFHOSTED=${PUBLIC_IS_SELFHOSTED} \
     -t ${DOCKERHUB_USERNAME}/dashboard:${VERSION} \
-    $(latest_arg ${DOCKERHUB_USERNAME}/dashboard) \
     --push \
     .
 echo -e "${GREEN}✓ Dashboard image published successfully!${NC}"
@@ -72,7 +67,6 @@ docker buildx build \
     --platform "${PLATFORMS}" \
     -f docker/Dockerfile.jobs \
     -t ${DOCKERHUB_USERNAME}/jobs:${VERSION} \
-    $(latest_arg ${DOCKERHUB_USERNAME}/jobs) \
     --push \
     .
 echo -e "${GREEN}✓ Jobs image published successfully!${NC}"

docker/docs/PUBLISHING_IMAGES.md

@@ -57,8 +57,8 @@ Check your Docker Hub repository at:
 
 The workflow will automatically publish images when:
 
-1. **Push to `main`**: Publishes the **`edge`** tag only (does NOT move `latest`).
-2. **Push a version tag `vX.Y.Z`**: Publishes `X.Y.Z`, `X.Y`, `X`, and `latest`.
+1. **Push to `main`**: Publishes the **`latest`** tag (the freshest `main` build).
+2. **Push a version tag `vX.Y.Z`**: Publishes `X.Y.Z`, `X.Y`, `X` (immutable, pinned releases).
 3. **Manual trigger**: Use the Actions tab in GitHub.
 
 Every build is **boot smoke-tested** (started against ephemeral postgres + redis, healthcheck
@@ -107,7 +107,7 @@ docker pull classroomio/dashboard:latest
 
 For self-hosting with Docker Compose, see [SELF_HOST.md](SELF_HOST.md). The setup uses a single root `.env` file and `docker-compose.yaml`.
 
-## Versioning Strategy (stable-releases + edge)
+## Versioning Strategy (rolling `latest` + pinned releases)
 
 The published tags and what they mean:
 
@@ -115,17 +115,15 @@ The published tags and what they mean:
 |-----|--------------|---------|
 | `1.4.2` (exact) | a `v1.4.2` git tag | Immutable, smoke-tested release — **what production should pin** |
 | `1.4`, `1` | a `v1.4.2` git tag | Latest patch/minor of that line |
-| `latest` | a `v*` git tag only | The newest *released* version |
-| `edge` | every push to `main` | Bleeding edge; may be unstable |
+| `latest` | every push to `main` | The freshest `main` build (rolling; may include unreleased code) |
 
-The key rule: **`latest` is never moved by a routine merge to `main`** — only a deliberate release
-tag moves it. Self-hosters pin `CIO_VERSION` (see [SELF_HOST.md](SELF_HOST.md)) and upgrade on their
-own schedule.
+The key rule: **`latest` moves on every merge to `main`**, so it can change under you. Self-hosters
+pin `CIO_VERSION` (see [SELF_HOST.md](SELF_HOST.md)) and upgrade on their own schedule.
 
 ### Cutting a release
 
 Versioning is driven by git tags; the CI workflow does the rest (build multi-arch → smoke-test →
-push `X.Y.Z`/`X.Y`/`X`/`latest`).
+push `X.Y.Z`/`X.Y`/`X`). `latest` is published separately, on every merge to `main`.
 
 ```bash
 # Bump version + create the vX.Y.Z tag from the repo's changelog tooling

docker/docs/SELF_HOST.md

@@ -44,18 +44,16 @@ From a full clone you can also use the helper: `./run-docker-full-stack.sh --ima
 
 ## Versioning & Upgrades
 
-Published images use a **stable-releases + edge** tag policy:
+Published images use a **rolling `latest` + pinned releases** tag policy:
 
 | Tag | Meaning | Use it for |
 |-----|---------|-----------|
 | `1.4.2` (exact) | An immutable, smoke-tested release | **Production — always pin this** |
 | `1.4`, `1` | Latest patch/minor of that line | Tracking a line |
-| `latest` | The newest *released* version | Trying it out |
-| `edge` | The last `main` build (may be unstable) | Testing upcoming changes |
+| `latest` | The freshest `main` build (rolling; may include unreleased code) | Trying the newest code |
 
-`latest` only moves when a real release is tagged — a routine merge to `main` publishes `edge`, never
-`latest`. **Pin `CIO_VERSION` to an exact version in production** so a new release can't break you
-unattended.
+`latest` moves on **every merge to `main`**, so it can change under you. **Pin `CIO_VERSION` to an
+exact version in production** so a merge can't break you unattended.
 
 ```bash
 # Upgrade: bump the version, pull, recreate