fix(docs): stop autoupdate PRs from rewriting source URLs every run (#516)

kvaps · web-flow · commit f466d343ff8b · 2026-05-12T12:41:59.000+02:00
## Summary - Decouple the displayed `source:` URL ref in synced docs from the fetch branch so patch releases and the daily cron stop flipping it on every run. - Realign existing `v1.0/` source URLs (which stamped `release-1.2.1`) to `release-1.0`. ## Context Auto-update PRs from this repo's daily cron, and from `cozystack/cozystack`'s release `tags.yaml`, were touching ~30 files per run for nothing more than swapping the `source:` line between `main`, `release-1.X`, and `vX.Y.Z`. The fetch ref and the displayed ref were the same value. `hack/update_apps.sh` now accepts an optional `--source-ref REF` (defaults to `--branch` for backward compat). The Makefile derives a stable `SOURCE_REF` from `DOC_VERSION`: | `DOC_VERSION` | `SOURCE_REF` | | --- | --- | | `v0` | `main` (legacy, preserves current state) | | `vX.Y` (X≥1) | `release-X.Y` | Fetch still uses `BRANCH` (the exact tag for reproducibility). ## Caller compatibility - Upstream `cozystack/cozystack` `tags.yaml`: `make update-all BRANCH=… RELEASE_TAG=…` — unchanged. - Website daily cron `update-managed-apps.yaml`: `make update-all DOC_VERSION=…` — unchanged. - Standalone `hack/update_apps.sh` runs without `--source-ref`: falls back to `--branch` (no behavior change). - `fill_templates.sh` doesn't touch `source:` URLs, so no changes there. ## Test plan - [x] `make -n update-apps` → `--source-ref release-1.2` - [x] `make -n update-apps RELEASE_TAG=v1.0.5` → `--source-ref release-1.0`, fetch from `v1.0.5` - [x] `make -n update-apps RELEASE_TAG=v1.2.5` → `--source-ref release-1.2`, fetch from `v1.2.5` - [x] `make -n update-apps RELEASE_TAG=v0.30.5` → `--source-ref main`, fetch from `v0.30.5` - [x] HEAD-checked all `release-1.0` README URLs used in v1.0 docs return 200 - [x] Standalone script run without `--source-ref` falls back to `--branch` (verified in temp dir) - [ ] Next post-merge auto-update PR (daily cron at 03:00 UTC, or next `cozystack/cozystack` release) should be small — touching only files whose upstream README content actually changed.  ## Summary by CodeRabbit * **Chores** * Build tooling now supports a separate source reference for generated documentation links (can differ from the branch used to fetch content). * **Documentation** * Updated autogenerated documentation source references across v1.0 content to point to the release-1.0 upstream. [![Review Change Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/cozystack/website/pull/516)
diff --git a/Makefile b/Makefile
@@ -47,6 +47,20 @@ else
   DOC_VERSION ?= next
 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)
+#   next  → main         (trunk tracks upstream main)
+#   vX.Y  → release-X.Y  (the upstream long-lived branch for that minor)
+ifeq ($(DOC_VERSION),v0)
+  SOURCE_REF ?= main
+else ifeq ($(DOC_VERSION),next)
+  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
@@ -64,19 +78,19 @@ SERVICES_DEST_DIR   ?= content/en/docs/$(DOC_VERSION)/operations/services
         init-version init-next release-next download-openapi download-openapi-all serve show-target
 
 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:
 	python3 hack/update_oss_health.py
diff --git a/content/en/docs/v1.0/applications/clickhouse.md b/content/en/docs/v1.0/applications/clickhouse.md
@@ -11,7 +11,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/clickhouse.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/clickhouse/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/clickhouse/README.md
 -->
 
 
diff --git a/content/en/docs/v1.0/applications/foundationdb.md b/content/en/docs/v1.0/applications/foundationdb.md
@@ -6,7 +6,7 @@ weight: 50
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/foundationdb.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/foundationdb/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/foundationdb/README.md
 -->
 
 
diff --git a/content/en/docs/v1.0/applications/harbor.md b/content/en/docs/v1.0/applications/harbor.md
@@ -7,7 +7,7 @@ weight: 50
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/harbor.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/harbor/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/harbor/README.md
 -->
 
 
diff --git a/content/en/docs/v1.0/applications/kafka.md b/content/en/docs/v1.0/applications/kafka.md
@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/kafka.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/kafka/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/kafka/README.md
 -->
 
 
diff --git a/content/en/docs/v1.0/applications/mariadb.md b/content/en/docs/v1.0/applications/mariadb.md
@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/mariadb.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/mariadb/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/mariadb/README.md
 -->
 
 
diff --git a/content/en/docs/v1.0/applications/mongodb.md b/content/en/docs/v1.0/applications/mongodb.md
@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/mongodb.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/mongodb/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/mongodb/README.md
 -->
 
 
diff --git a/content/en/docs/v1.0/applications/nats.md b/content/en/docs/v1.0/applications/nats.md
@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/nats.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/nats/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/nats/README.md
 -->
 
 
diff --git a/content/en/docs/v1.0/applications/openbao.md b/content/en/docs/v1.0/applications/openbao.md
@@ -7,7 +7,7 @@ weight: 50
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/openbao.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/openbao/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/openbao/README.md
 -->
 
 
diff --git a/content/en/docs/v1.0/applications/postgres.md b/content/en/docs/v1.0/applications/postgres.md
@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/postgres.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/postgres/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/postgres/README.md
 -->
 
 
diff --git a/content/en/docs/v1.0/applications/qdrant.md b/content/en/docs/v1.0/applications/qdrant.md
@@ -7,7 +7,7 @@ weight: 50
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/qdrant.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/qdrant/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/qdrant/README.md
 -->
 
 
diff --git a/content/en/docs/v1.0/applications/rabbitmq.md b/content/en/docs/v1.0/applications/rabbitmq.md
@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/rabbitmq.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/rabbitmq/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/rabbitmq/README.md
 -->
 
 
diff --git a/content/en/docs/v1.0/applications/redis.md b/content/en/docs/v1.0/applications/redis.md
@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/redis.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/redis/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/redis/README.md
 -->
 
 
diff --git a/content/en/docs/v1.0/applications/tenant.md b/content/en/docs/v1.0/applications/tenant.md
@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/tenant.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/tenant/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/tenant/README.md
 -->
 
 
diff --git a/content/en/docs/v1.0/kubernetes/_index.md b/content/en/docs/v1.0/kubernetes/_index.md
@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/kubernetes/_include/_index.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/kubernetes/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/kubernetes/README.md
 -->
 
 
diff --git 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:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/networking/_include/http-cache.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/http-cache/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/http-cache/README.md
 -->
 
 
diff --git 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:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/networking/_include/tcp-balancer.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/tcp-balancer/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/tcp-balancer/README.md
 -->
 
 
diff --git a/content/en/docs/v1.0/networking/vpc.md b/content/en/docs/v1.0/networking/vpc.md
@@ -11,7 +11,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/networking/_include/vpc.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/vpc/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/vpc/README.md
 -->
 
 
diff --git a/content/en/docs/v1.0/networking/vpn.md b/content/en/docs/v1.0/networking/vpn.md
@@ -11,7 +11,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/networking/_include/vpn.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/vpn/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/vpn/README.md
 -->
 
 
diff --git 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"
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/operations/services/_include/bootbox.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/extra/bootbox/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/extra/bootbox/README.md
 -->
 
 
diff --git 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"
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/operations/services/_include/etcd.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/extra/etcd/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/extra/etcd/README.md
 -->
 
 
diff --git 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"
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/operations/services/_include/ingress.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/extra/ingress/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/extra/ingress/README.md
 -->
 
 
diff --git 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
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/operations/services/_include/parameters.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/extra/monitoring/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/extra/monitoring/README.md
 -->
 
 
diff --git 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"
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/operations/services/_include/seaweedfs.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/extra/seaweedfs/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/extra/seaweedfs/README.md
 -->
 
 
diff --git 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:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/virtualization/_include/vm-disk.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/vm-disk/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/vm-disk/README.md
 -->
 
 
diff --git 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:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/virtualization/_include/vm-instance.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/vm-instance/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/vm-instance/README.md
 -->
 
 
diff --git 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/<app>/_index.md instead of path/<app>.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/<app>/_index.md instead of path/<app>.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
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/${DOCS_REPO}/blob/main/${rel_template_path}
-source: https://github.com/${SOURCE_REPO}/blob/${BRANCH}/packages/${PKG_DIR}/${app}/README.md
+source: https://github.com/${SOURCE_REPO}/blob/${SOURCE_REF}/packages/${PKG_DIR}/${app}/README.md
 -->
 
 EOF
