Skip to content

Commit cd81a65

Browse files
feat(hack): generate docs from a pre-tag ref and fail loudly on fetch errors
update-all could only fetch content from a ref named exactly like RELEASE_TAG (the Makefile overrides BRANCH with it), which forces docs generation to wait until the final tag exists. The new FETCH_REF variable (default: BRANCH, so every existing invocation is byte-identical) lets the release flow point content fetching at a staging branch, rc tag, or SHA while version routing still keys on RELEASE_TAG — enabling the docs PR to be prepared at promote time, before the stable tag is cut. update_apps.sh also rewrote destination docs before fetching and swallowed curl failures, so a bad ref or a raw.githubusercontent hiccup silently produced stub docs that could be committed and merged. Fetch now goes to a temp file first with curl --retry 3; any fetch failure or empty body aborts non-zero with the app and URL named, leaving existing docs byte-identical. A trap covers temp cleanup on the non-fetch error paths. Note the intended strictness: update-all against an older tag whose tree lacks a currently-listed app now fails the job instead of committing a stub for it. Assisted-By: GPT-5 <[email protected]> Assisted-By: Claude <[email protected]> Signed-off-by: Myasnikov Daniil <[email protected]>
1 parent c9bb53d commit cd81a65

2 files changed

Lines changed: 38 additions & 17 deletions

File tree

‎Makefile‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,11 @@ else
2323
BRANCH ?= main
2424
endif
2525

26+
# FETCH_REF is the ref content is fetched from. It defaults to BRANCH (which is
27+
# pinned to RELEASE_TAG when set); override it with a staging branch, RC tag, or
28+
# SHA to generate docs before the final tag exists.
29+
FETCH_REF ?= $(BRANCH)
30+
2631
# Non-empty when RELEASE_TAG carries a prerelease suffix (-rc.N / -beta.N /
2732
# -alpha.N). Used to skip trunk pin regeneration on prereleases — update_versions.sh
2833
# only accepts final vX.Y.Z tags, and the trunk should track the latest final release.
@@ -84,19 +89,19 @@ SERVICES_DEST_DIR ?= content/en/docs/$(DOC_VERSION)/operations/services
8489
init-version init-next release-next download-openapi download-openapi-all serve show-target
8590

8691
update-apps:
87-
./hack/update_apps.sh --apps "$(APPS)" --dest "$(APPS_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)"
92+
./hack/update_apps.sh --apps "$(APPS)" --dest "$(APPS_DEST_DIR)" --branch "$(FETCH_REF)" --source-ref "$(SOURCE_REF)"
8893

8994
update-vms:
90-
./hack/update_apps.sh --apps "$(VMS)" --dest "$(VMS_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)"
95+
./hack/update_apps.sh --apps "$(VMS)" --dest "$(VMS_DEST_DIR)" --branch "$(FETCH_REF)" --source-ref "$(SOURCE_REF)"
9196

9297
update-networking:
93-
./hack/update_apps.sh --apps "$(NETWORKING)" --dest "$(NETWORKING_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)"
98+
./hack/update_apps.sh --apps "$(NETWORKING)" --dest "$(NETWORKING_DEST_DIR)" --branch "$(FETCH_REF)" --source-ref "$(SOURCE_REF)"
9499

95100
update-k8s:
96-
./hack/update_apps.sh --index --apps "$(K8S)" --dest "$(K8S_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)"
101+
./hack/update_apps.sh --index --apps "$(K8S)" --dest "$(K8S_DEST_DIR)" --branch "$(FETCH_REF)" --source-ref "$(SOURCE_REF)"
97102

98103
update-services:
99-
./hack/update_apps.sh --apps "$(SERVICES)" --dest "$(SERVICES_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)" --pkgdir extra
104+
./hack/update_apps.sh --apps "$(SERVICES)" --dest "$(SERVICES_DEST_DIR)" --branch "$(FETCH_REF)" --source-ref "$(SOURCE_REF)" --pkgdir extra
100105

101106
update-oss-health:
102107
python3 hack/update_oss_health.py
@@ -139,6 +144,7 @@ show-target:
139144
@echo "RELEASE_TAG=$(RELEASE_TAG)"
140145
@echo "DOC_VERSION=$(DOC_VERSION)"
141146
@echo "BRANCH=$(BRANCH)"
147+
@echo "FETCH_REF=$(FETCH_REF)"
142148

143149
# Update the target directory in place. Routing rules above determine whether
144150
# this writes into next/ or an existing released version directory.
@@ -162,7 +168,7 @@ update-all:
162168
update-versions:
163169
ifeq ($(DOC_VERSION),next)
164170
ifeq ($(_is_prerelease),)
165-
./hack/update_versions.sh --dest data/versions/next.yaml --branch "$(BRANCH)" $(if $(RELEASE_TAG),--cozystack-tag "$(RELEASE_TAG)")
171+
./hack/update_versions.sh --dest data/versions/next.yaml --branch "$(FETCH_REF)" $(if $(RELEASE_TAG),--cozystack-tag "$(RELEASE_TAG)")
166172
else
167173
@echo "update-versions: prerelease $(RELEASE_TAG) — skipping trunk pin refresh (pins track the latest final release)."
168174
endif

‎hack/update_apps.sh‎

Lines changed: 26 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,10 @@ SOURCE_REPO="cozystack/cozystack"
8383
RAW_BASE_URL="https://raw.githubusercontent.com/${SOURCE_REPO}/${BRANCH}/packages/${PKG_DIR}"
8484

8585

86+
# The per-app temp file is removed on every explicit exit path below; the trap
87+
# covers aborts between mktemp and those paths (set -e on touch/cp/heredoc).
88+
trap 'rm -f "${tmp:-}"' EXIT
89+
8690
for app in "${APPS[@]}"; do
8791
if [[ "$INDEX_MODE" == "true" ]]; then
8892
src_file="${DEST_DIR%/}/${app}/_include/_index.md"
@@ -97,6 +101,24 @@ for app in "${APPS[@]}"; do
97101
fi
98102
fi
99103

104+
readme_url="${RAW_BASE_URL}/${app}/README.md"
105+
echo "Processing $app..."
106+
107+
tmp=$(mktemp)
108+
if ! curl -fsSL --compressed --retry 3 "$readme_url" \
109+
| sed '1s/\xEF\xBB\xBF//' \
110+
| awk 'NR==1 && /^#{1,2} / { next } { print }' > "$tmp"; then
111+
rm -f "$tmp"
112+
echo "Error: failed to fetch README for $app from $readme_url" >&2
113+
exit 1
114+
fi
115+
116+
if [[ ! -s "$tmp" ]]; then
117+
rm -f "$tmp"
118+
echo "Error: fetched empty README for $app from $readme_url" >&2
119+
exit 1
120+
fi
121+
100122
# Ensure template exists (touch if missing)
101123
[[ -f "$src_file" ]] || touch "$src_file"
102124

@@ -114,15 +136,8 @@ source: https://github.com/${SOURCE_REPO}/blob/${SOURCE_REF}/packages/${PKG_DIR}
114136
115137
EOF
116138

117-
readme_url="${RAW_BASE_URL}/${app}/README.md"
118-
echo "Processing $app..."
119-
120-
if curl -fsSL --compressed "$readme_url" \
121-
| sed '1s/\xEF\xBB\xBF//' \
122-
| awk 'NR==1 && /^#{1,2} / { next } { print }' >> "$dest_file"; then
123-
echo "✓ Appended README for $app -> $dest_file"
124-
else
125-
echo "⚠️ Failed to fetch README for $app" >&2
126-
fi
139+
cat "$tmp" >> "$dest_file"
140+
rm -f "$tmp"
141+
echo "✓ Appended README for $app -> $dest_file"
127142

128-
done
143+
done

0 commit comments

Comments
 (0)