From bae50a94527e5e4dd301b7c337a7ad7350328b49 Mon Sep 17 00:00:00 2001 From: Myasnikov Daniil Date: Tue, 28 Apr 2026 17:20:54 +0500 Subject: [PATCH 1/2] fix(ci): decouple displayed source ref from fetch branch in synced docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `hack/update_apps.sh` writes a `source:` URL into every generated file. It previously used the same git ref for both fetching READMEs and rendering that URL — which meant every patch release rewrote `source:` from `release-X.Y` → `vX.Y.Z`, and the daily cron rewrote it again to `main`. Result: every auto-update PR touched ~30 files solely to flip the ref. Add an optional `--source-ref REF` flag to `update_apps.sh` (defaults to `--branch` for backward compat) and derive a stable `SOURCE_REF` in the Makefile from `DOC_VERSION`: v0 → main (legacy bucket, preserves current state) vX.Y → release-X.Y (long-lived upstream branch for that minor) Fetch still uses the exact tag (BRANCH) for reproducibility; only the displayed URL is stabilized. No change to caller signatures (`make update-all RELEASE_TAG=…` for the upstream tags workflow, `make update-all DOC_VERSION=…` for the daily cron) — both keep working. Signed-off-by: Myasnikov Daniil --- Makefile | 21 ++++++++++++++++----- hack/update_apps.sh | 23 ++++++++++++++++------- 2 files changed, 32 insertions(+), 12 deletions(-) diff --git a/Makefile b/Makefile index 6f05948c..d19e67ef 100644 --- a/Makefile +++ b/Makefile @@ -12,6 +12,17 @@ else BRANCH ?= main endif +# SOURCE_REF: stable git ref written into the displayed `source:` URL of generated docs. +# Decoupled from BRANCH (which fetches content) so that patch releases of the same +# minor don't churn every file's source URL on every release. +# v0 → main (legacy bucket; many 0.x tags share this dir) +# vX.Y → release-X.Y (the upstream long-lived branch for that minor) +ifeq ($(DOC_VERSION),v0) + SOURCE_REF ?= main +else + SOURCE_REF ?= release-$(patsubst v%,%,$(DOC_VERSION)) +endif + # App lists (override on the command line: `make update-apps APPS="tenant redis"`) APPS ?= tenant clickhouse foundationdb harbor redis mongodb openbao rabbitmq postgres nats kafka mariadb qdrant K8S ?= kubernetes @@ -29,19 +40,19 @@ SERVICES_DEST_DIR ?= content/en/docs/$(DOC_VERSION)/operations/services init-version download-openapi download-openapi-all serve update-apps: - ./hack/update_apps.sh --apps "$(APPS)" --dest "$(APPS_DEST_DIR)" --branch "$(BRANCH)" + ./hack/update_apps.sh --apps "$(APPS)" --dest "$(APPS_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)" update-vms: - ./hack/update_apps.sh --apps "$(VMS)" --dest "$(VMS_DEST_DIR)" --branch "$(BRANCH)" + ./hack/update_apps.sh --apps "$(VMS)" --dest "$(VMS_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)" update-networking: - ./hack/update_apps.sh --apps "$(NETWORKING)" --dest "$(NETWORKING_DEST_DIR)" --branch "$(BRANCH)" + ./hack/update_apps.sh --apps "$(NETWORKING)" --dest "$(NETWORKING_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)" update-k8s: - ./hack/update_apps.sh --index --apps "$(K8S)" --dest "$(K8S_DEST_DIR)" --branch "$(BRANCH)" + ./hack/update_apps.sh --index --apps "$(K8S)" --dest "$(K8S_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)" update-services: - ./hack/update_apps.sh --apps "$(SERVICES)" --dest "$(SERVICES_DEST_DIR)" --branch "$(BRANCH)" --pkgdir extra + ./hack/update_apps.sh --apps "$(SERVICES)" --dest "$(SERVICES_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)" --pkgdir extra update-oss-health: ./hack/update_oss_health.py diff --git a/hack/update_apps.sh b/hack/update_apps.sh index c4134292..3f00cf3d 100755 --- a/hack/update_apps.sh +++ b/hack/update_apps.sh @@ -6,12 +6,15 @@ usage() { Usage: hack/update_apps.sh [OPTIONS] Options: - --branch BRANCH Git branch in cozystack/cozystack (default: main) - --apps LIST Space- or comma-separated list of apps to update - --dest PATH Destination directory to write the *.md files to - --pkgdir DIR Subdirectory under packages/ to fetch from (default: apps). Examples: apps, extra - --index Write each app into path//_index.md instead of path/.md (creates subdirectory) - -h, --help Show this help and exit + --branch BRANCH Git ref in cozystack/cozystack used to FETCH README content (default: main) + --source-ref REF Git ref written into the displayed `source:` URL inside generated files. + Defaults to --branch if omitted. Use a stable ref (e.g., release-1.2) to + avoid flipping the source URL on every patch release. + --apps LIST Space- or comma-separated list of apps to update + --dest PATH Destination directory to write the *.md files to + --pkgdir DIR Subdirectory under packages/ to fetch from (default: apps). Examples: apps, extra + --index Write each app into path//_index.md instead of path/.md (creates subdirectory) + -h, --help Show this help and exit Notes: * Template markdown files are expected in DEST_DIR/_include (derived automatically). @@ -24,6 +27,7 @@ EOF } BRANCH="main" +SOURCE_REF="" DEST_DIR="" APPS=() INDEX_MODE="false" @@ -34,6 +38,8 @@ while [[ $# -gt 0 ]]; do case "$1" in --branch) BRANCH="$2"; shift 2 ;; + --source-ref) + SOURCE_REF="$2"; shift 2 ;; --apps) IFS=', ' read -r -a APPS <<< "$2"; shift 2 ;; --dest) @@ -69,6 +75,9 @@ fi # Derive templates location: DEST_DIR/_include SRC_DIR="${DEST_DIR%/}/_include" +# If --source-ref wasn't given, fall back to the fetch branch (preserves prior behavior) +SOURCE_REF="${SOURCE_REF:-$BRANCH}" + DOCS_REPO="cozystack/website" SOURCE_REPO="cozystack/cozystack" RAW_BASE_URL="https://raw.githubusercontent.com/${SOURCE_REPO}/${BRANCH}/packages/${PKG_DIR}" @@ -100,7 +109,7 @@ for app in "${APPS[@]}"; do EOF From a2e6517b6cc553c5a30707d2e57c2d0ab1a25a33 Mon Sep 17 00:00:00 2001 From: Myasnikov Daniil Date: Tue, 28 Apr 2026 17:21:01 +0500 Subject: [PATCH 2/2] fix(docs): point v1.0 source URLs at release-1.0 branch MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The v1.0 generated docs all stamped `release-1.2.1` as the source ref (left behind from a stale generation pass). Realign them with the versioned scheme introduced in the previous commit, so v1.0 docs link to upstream READMEs on the `release-1.0` branch. Surgical sed-replace of the source URL line only — no content changes. Signed-off-by: Myasnikov Daniil --- content/en/docs/v1.0/applications/clickhouse.md | 2 +- content/en/docs/v1.0/applications/foundationdb.md | 2 +- content/en/docs/v1.0/applications/harbor.md | 2 +- content/en/docs/v1.0/applications/kafka.md | 2 +- content/en/docs/v1.0/applications/mariadb.md | 2 +- content/en/docs/v1.0/applications/mongodb.md | 2 +- content/en/docs/v1.0/applications/nats.md | 2 +- content/en/docs/v1.0/applications/openbao.md | 2 +- content/en/docs/v1.0/applications/postgres.md | 2 +- content/en/docs/v1.0/applications/qdrant.md | 2 +- content/en/docs/v1.0/applications/rabbitmq.md | 2 +- content/en/docs/v1.0/applications/redis.md | 2 +- content/en/docs/v1.0/applications/tenant.md | 2 +- content/en/docs/v1.0/kubernetes/_index.md | 2 +- content/en/docs/v1.0/networking/http-cache.md | 2 +- content/en/docs/v1.0/networking/tcp-balancer.md | 2 +- content/en/docs/v1.0/networking/vpc.md | 2 +- content/en/docs/v1.0/networking/vpn.md | 2 +- content/en/docs/v1.0/operations/services/bootbox.md | 2 +- content/en/docs/v1.0/operations/services/etcd.md | 2 +- content/en/docs/v1.0/operations/services/ingress.md | 2 +- .../en/docs/v1.0/operations/services/monitoring/parameters.md | 2 +- content/en/docs/v1.0/operations/services/seaweedfs.md | 2 +- content/en/docs/v1.0/virtualization/vm-disk.md | 2 +- content/en/docs/v1.0/virtualization/vm-instance.md | 2 +- 25 files changed, 25 insertions(+), 25 deletions(-) diff --git a/content/en/docs/v1.0/applications/clickhouse.md b/content/en/docs/v1.0/applications/clickhouse.md index b4cda288..9a0ba856 100644 --- a/content/en/docs/v1.0/applications/clickhouse.md +++ b/content/en/docs/v1.0/applications/clickhouse.md @@ -11,7 +11,7 @@ aliases: diff --git a/content/en/docs/v1.0/applications/foundationdb.md b/content/en/docs/v1.0/applications/foundationdb.md index b8ec2c53..7766f5d9 100644 --- a/content/en/docs/v1.0/applications/foundationdb.md +++ b/content/en/docs/v1.0/applications/foundationdb.md @@ -6,7 +6,7 @@ weight: 50 diff --git a/content/en/docs/v1.0/applications/harbor.md b/content/en/docs/v1.0/applications/harbor.md index 5cfc88e2..f05b24ea 100644 --- a/content/en/docs/v1.0/applications/harbor.md +++ b/content/en/docs/v1.0/applications/harbor.md @@ -7,7 +7,7 @@ weight: 50 diff --git a/content/en/docs/v1.0/applications/kafka.md b/content/en/docs/v1.0/applications/kafka.md index f376c087..2ac9aa69 100644 --- a/content/en/docs/v1.0/applications/kafka.md +++ b/content/en/docs/v1.0/applications/kafka.md @@ -10,7 +10,7 @@ aliases: diff --git a/content/en/docs/v1.0/applications/mariadb.md b/content/en/docs/v1.0/applications/mariadb.md index 8d15d4d1..78c0326d 100644 --- a/content/en/docs/v1.0/applications/mariadb.md +++ b/content/en/docs/v1.0/applications/mariadb.md @@ -10,7 +10,7 @@ aliases: diff --git a/content/en/docs/v1.0/applications/mongodb.md b/content/en/docs/v1.0/applications/mongodb.md index 98d7f491..9d5cbbbc 100644 --- a/content/en/docs/v1.0/applications/mongodb.md +++ b/content/en/docs/v1.0/applications/mongodb.md @@ -10,7 +10,7 @@ aliases: diff --git a/content/en/docs/v1.0/applications/nats.md b/content/en/docs/v1.0/applications/nats.md index fe6f4c28..f18b63a3 100644 --- a/content/en/docs/v1.0/applications/nats.md +++ b/content/en/docs/v1.0/applications/nats.md @@ -10,7 +10,7 @@ aliases: diff --git a/content/en/docs/v1.0/applications/openbao.md b/content/en/docs/v1.0/applications/openbao.md index faf0ad64..332199dc 100644 --- a/content/en/docs/v1.0/applications/openbao.md +++ b/content/en/docs/v1.0/applications/openbao.md @@ -7,7 +7,7 @@ weight: 50 diff --git a/content/en/docs/v1.0/applications/postgres.md b/content/en/docs/v1.0/applications/postgres.md index e36b7557..a87e9260 100644 --- a/content/en/docs/v1.0/applications/postgres.md +++ b/content/en/docs/v1.0/applications/postgres.md @@ -10,7 +10,7 @@ aliases: diff --git a/content/en/docs/v1.0/applications/qdrant.md b/content/en/docs/v1.0/applications/qdrant.md index 027b045e..b6a9d533 100644 --- a/content/en/docs/v1.0/applications/qdrant.md +++ b/content/en/docs/v1.0/applications/qdrant.md @@ -7,7 +7,7 @@ weight: 50 diff --git a/content/en/docs/v1.0/applications/rabbitmq.md b/content/en/docs/v1.0/applications/rabbitmq.md index 84936d9d..bdf805b7 100644 --- a/content/en/docs/v1.0/applications/rabbitmq.md +++ b/content/en/docs/v1.0/applications/rabbitmq.md @@ -10,7 +10,7 @@ aliases: diff --git a/content/en/docs/v1.0/applications/redis.md b/content/en/docs/v1.0/applications/redis.md index 47c03890..d81eedd6 100644 --- a/content/en/docs/v1.0/applications/redis.md +++ b/content/en/docs/v1.0/applications/redis.md @@ -10,7 +10,7 @@ aliases: diff --git a/content/en/docs/v1.0/applications/tenant.md b/content/en/docs/v1.0/applications/tenant.md index 2d4a208e..1270d31f 100644 --- a/content/en/docs/v1.0/applications/tenant.md +++ b/content/en/docs/v1.0/applications/tenant.md @@ -10,7 +10,7 @@ aliases: diff --git a/content/en/docs/v1.0/kubernetes/_index.md b/content/en/docs/v1.0/kubernetes/_index.md index 7e7ad748..84b766bc 100644 --- a/content/en/docs/v1.0/kubernetes/_index.md +++ b/content/en/docs/v1.0/kubernetes/_index.md @@ -10,7 +10,7 @@ aliases: diff --git a/content/en/docs/v1.0/networking/http-cache.md b/content/en/docs/v1.0/networking/http-cache.md index 8d78e9c6..377b1035 100644 --- a/content/en/docs/v1.0/networking/http-cache.md +++ b/content/en/docs/v1.0/networking/http-cache.md @@ -11,7 +11,7 @@ aliases: diff --git a/content/en/docs/v1.0/networking/tcp-balancer.md b/content/en/docs/v1.0/networking/tcp-balancer.md index 1efed51a..616d32e0 100644 --- a/content/en/docs/v1.0/networking/tcp-balancer.md +++ b/content/en/docs/v1.0/networking/tcp-balancer.md @@ -11,7 +11,7 @@ aliases: diff --git a/content/en/docs/v1.0/networking/vpc.md b/content/en/docs/v1.0/networking/vpc.md index b127bf53..72b48384 100644 --- a/content/en/docs/v1.0/networking/vpc.md +++ b/content/en/docs/v1.0/networking/vpc.md @@ -11,7 +11,7 @@ aliases: diff --git a/content/en/docs/v1.0/networking/vpn.md b/content/en/docs/v1.0/networking/vpn.md index d47af63c..dc3f70ca 100644 --- a/content/en/docs/v1.0/networking/vpn.md +++ b/content/en/docs/v1.0/networking/vpn.md @@ -11,7 +11,7 @@ aliases: diff --git a/content/en/docs/v1.0/operations/services/bootbox.md b/content/en/docs/v1.0/operations/services/bootbox.md index 5b23b9b9..17ee1247 100644 --- a/content/en/docs/v1.0/operations/services/bootbox.md +++ b/content/en/docs/v1.0/operations/services/bootbox.md @@ -6,7 +6,7 @@ linkTitle: "BootBox" diff --git a/content/en/docs/v1.0/operations/services/etcd.md b/content/en/docs/v1.0/operations/services/etcd.md index 7c857b09..f96cc3fd 100644 --- a/content/en/docs/v1.0/operations/services/etcd.md +++ b/content/en/docs/v1.0/operations/services/etcd.md @@ -6,7 +6,7 @@ linkTitle: "Etcd" diff --git a/content/en/docs/v1.0/operations/services/ingress.md b/content/en/docs/v1.0/operations/services/ingress.md index 74a4f70c..fff6590e 100644 --- a/content/en/docs/v1.0/operations/services/ingress.md +++ b/content/en/docs/v1.0/operations/services/ingress.md @@ -6,7 +6,7 @@ linkTitle: "Ingress" diff --git a/content/en/docs/v1.0/operations/services/monitoring/parameters.md b/content/en/docs/v1.0/operations/services/monitoring/parameters.md index bce85911..f2cbdc56 100644 --- a/content/en/docs/v1.0/operations/services/monitoring/parameters.md +++ b/content/en/docs/v1.0/operations/services/monitoring/parameters.md @@ -7,7 +7,7 @@ weight: 1 diff --git a/content/en/docs/v1.0/operations/services/seaweedfs.md b/content/en/docs/v1.0/operations/services/seaweedfs.md index 277c72bf..84d3e7c2 100644 --- a/content/en/docs/v1.0/operations/services/seaweedfs.md +++ b/content/en/docs/v1.0/operations/services/seaweedfs.md @@ -6,7 +6,7 @@ linkTitle: "SeaweedFS" diff --git a/content/en/docs/v1.0/virtualization/vm-disk.md b/content/en/docs/v1.0/virtualization/vm-disk.md index 72618326..c6a6e8ef 100644 --- a/content/en/docs/v1.0/virtualization/vm-disk.md +++ b/content/en/docs/v1.0/virtualization/vm-disk.md @@ -10,7 +10,7 @@ aliases: diff --git a/content/en/docs/v1.0/virtualization/vm-instance.md b/content/en/docs/v1.0/virtualization/vm-instance.md index f75eb095..af3042df 100644 --- a/content/en/docs/v1.0/virtualization/vm-instance.md +++ b/content/en/docs/v1.0/virtualization/vm-instance.md @@ -10,7 +10,7 @@ aliases: