From 8f8a6f2dc87acb12a0fca2dc4f5862c1a2e67ea4 Mon Sep 17 00:00:00 2001
From: Yassine Doghri <yassine@doghri.fr>
Date: Thu, 19 Feb 2026 12:14:53 +0000
Subject: [PATCH] build(docker): set major version channel tags to prevent
 major breaking changes (`1`, `2-next`, ...)

---
 docker/production/.gitlab-ci.yml              | 24 ++++++++++++-------
 .../docs/en/getting-started/docker.mdx        | 17 ++++++-------
 2 files changed, 25 insertions(+), 16 deletions(-)

diff --git a/docker/production/.gitlab-ci.yml b/docker/production/.gitlab-ci.yml
index 0b2ee2d5..6256cc13 100644
--- a/docker/production/.gitlab-ci.yml
+++ b/docker/production/.gitlab-ci.yml
@@ -60,10 +60,16 @@ docker-build-release:
     # copy credentials to authenticate against registry
     - cp ${DOCKER_HUB_CONFIG} /root/.docker/config.json
 
-    # extract Castopod version from tag (remove "v" prefix)
-    - export CP_VERSION=$(echo "$CI_COMMIT_TAG" | sed 's/^v//')
-    # extract pre release identifier (eg. alpha, beta, next, ...) from CP_VERSION or "latest" if none exists
-    - export CP_TAG=$(echo "$CP_VERSION" | sed 's/^[^-]*-\([^.]*\)\..*/\1/; t; s/.*/latest/')
+    ## Prepare Docker image tags from git tag
+    ## --------------------------------------
+    # extract full SemVer from git tag (remove leading "v")
+    - export IMAGE_TAG_VERSION=$(echo "$CI_COMMIT_TAG" | sed 's/^v//')
+    # extract channel (prerelease like "alpha", "beta", "next"; "latest" for stable)
+    - export IMAGE_TAG_CHANNEL=$(echo "$IMAGE_TAG_VERSION" | sed 's/^[^-]*-\([^.]*\)\..*/\1/; t; s/.*/latest/')
+    # extract major version number (first SemVer component)
+    - export IMAGE_TAG_MAJOR=$(echo "$IMAGE_TAG_VERSION" | sed 's/\..*//')
+    # construct major-channel tag ("X" for stable, "X-channel" for prerelease)
+    - export IMAGE_TAG_MAJOR_CHANNEL=$([ "$IMAGE_TAG_CHANNEL" = "latest" ] && echo "$IMAGE_TAG_MAJOR" || echo "${IMAGE_TAG_MAJOR}-${IMAGE_TAG_CHANNEL}")
 
     - docker context create tls-environment
 
@@ -86,8 +92,9 @@ docker-build-release:
       --platform linux/amd64
       --file docker/production/Dockerfile
       --push
-      --tag ${DOCKER_IMAGE_CASTOPOD}:${CP_VERSION}
-      --tag ${DOCKER_IMAGE_CASTOPOD}:${CP_TAG}
+      --tag ${DOCKER_IMAGE_CASTOPOD}:${IMAGE_TAG_VERSION}
+      --tag ${DOCKER_IMAGE_CASTOPOD}:${IMAGE_TAG_CHANNEL}
+      --tag ${DOCKER_IMAGE_CASTOPOD}:${IMAGE_TAG_MAJOR_CHANNEL}
       .
     # when --platform=linux/amd64,linux/arm64: amd64 image takes too long to be pushed as it needs to wait for arm64 to be built
     # --> build and push amd64 image first, then overwrite manifest after building arm64
@@ -97,8 +104,9 @@ docker-build-release:
       --platform linux/amd64,linux/arm64
       --file docker/production/Dockerfile
       --push
-      --tag ${DOCKER_IMAGE_CASTOPOD}:${CP_VERSION}
-      --tag ${DOCKER_IMAGE_CASTOPOD}:${CP_TAG}
+      --tag ${DOCKER_IMAGE_CASTOPOD}:${IMAGE_TAG_VERSION}
+      --tag ${DOCKER_IMAGE_CASTOPOD}:${IMAGE_TAG_CHANNEL}
+      --tag ${DOCKER_IMAGE_CASTOPOD}:${IMAGE_TAG_MAJOR_CHANNEL}
       .
   rules:
     - if: $CI_COMMIT_TAG
diff --git a/docs/src/content/docs/en/getting-started/docker.mdx b/docs/src/content/docs/en/getting-started/docker.mdx
index 0a8e0dfa..e129904d 100644
--- a/docs/src/content/docs/en/getting-started/docker.mdx
+++ b/docs/src/content/docs/en/getting-started/docker.mdx
@@ -17,18 +17,19 @@ service can be configured as the caching layer.
 
 ## Supported tags
 
-- `1.x.x` [stable], specific version build (since `1.0.0`)
-- `latest` [stable], latest version build
+- `1.x.x`, specific version build (since `1.0.0`)
+- `1`, latest build for version 1
+- `latest`, latest version build
 - `develop` [unstable], latest development branch build
 
-Other unstable tags (e.g., `beta`, `next`) may be actively pushed during development phases.
+Other unstable channels (e.g., `beta`, `next`, `2-next`) may be actively pushed during development phases.
 See [all tags in the docker hub](https://hub.docker.com/r/castopod/castopod/tags).
 
-<Aside type="tip">
-  To ensure reproducibility and stability during production, always pin to a
-  specific version tag like `1.x.x` (e.g., `1.15.1`) instead of `latest`.
+<Aside type="caution">
+  For production stability, prefer specific tags like `1.x.x` (e.g., `1.15.1`)
+  over generic channels (e.g., `latest`, `1`).
   <br />
-  The latest tag changes unexpectedly, risking downtime and inconsistent
+  Generic tags change unexpectedly, risking downtime and inconsistent
   deployments.
 </Aside>
 
@@ -41,7 +42,7 @@ See [all tags in the docker hub](https://hub.docker.com/r/castopod/castopod/tags
     ```yml
     services:
       castopod:
-        image: castopod/castopod:latest # Pin to a specific version during production
+        image: castopod/castopod:1 # Pin to a specific version during production
         container_name: "castopod"
         volumes:
           - castopod-media:/app/public/media