Skip to content

feat(hack): generate docs from a pre-tag ref and fail loudly on fetch errors #631

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
myasnikovdaniil wants to merge 2 commits into
base: main
Choose a base branch
from
+38 −17
Open

feat(hack): generate docs from a pre-tag ref and fail loudly on fetch errors #631

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8bcd256
feat(hack): generate docs from a pre-tag ref and fail loudly on fetch…
myasnikovdaniil Jul 24, 2026
08f1200
Merge branch 'main' into feat/prerelease-fetch-ref
myasnikovdaniil Jul 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 12 additions & 6 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,11 @@ else
BRANCH ?= main
endif

# FETCH_REF is the ref content is fetched from. It defaults to BRANCH (which is
# pinned to RELEASE_TAG when set); override it with a staging branch, RC tag, or
# SHA to generate docs before the final tag exists.
FETCH_REF ?= $(BRANCH)

# Non-empty when RELEASE_TAG carries a prerelease suffix (-rc.N / -beta.N /
# -alpha.N). Used to skip trunk pin regeneration on prereleases — update_versions.sh
# only accepts final vX.Y.Z tags, and the trunk should track the latest final release.
Expand Down Expand Up @@ -84,19 +89,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)" --source-ref "$(SOURCE_REF)"
./hack/update_apps.sh --apps "$(APPS)" --dest "$(APPS_DEST_DIR)" --branch "$(FETCH_REF)" --source-ref "$(SOURCE_REF)"

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

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

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

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

update-oss-health:
python3 hack/update_oss_health.py
Expand Down Expand Up @@ -139,6 +144,7 @@ show-target:
@echo "RELEASE_TAG=$(RELEASE_TAG)"
@echo "DOC_VERSION=$(DOC_VERSION)"
@echo "BRANCH=$(BRANCH)"
@echo "FETCH_REF=$(FETCH_REF)"

# Update the target directory in place. Routing rules above determine whether
# this writes into next/ or an existing released version directory.
Expand All @@ -162,7 +168,7 @@ update-all:
update-versions:
ifeq ($(DOC_VERSION),next)
ifeq ($(_is_prerelease),)
./hack/update_versions.sh --dest data/versions/next.yaml --branch "$(BRANCH)" $(if $(RELEASE_TAG),--cozystack-tag "$(RELEASE_TAG)")
./hack/update_versions.sh --dest data/versions/next.yaml --branch "$(FETCH_REF)" $(if $(RELEASE_TAG),--cozystack-tag "$(RELEASE_TAG)")
else
@echo "update-versions: prerelease $(RELEASE_TAG) — skipping trunk pin refresh (pins track the latest final release)."
endif
Expand Down
37 changes: 26 additions & 11 deletions hack/update_apps.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,10 @@ SOURCE_REPO="cozystack/cozystack"
RAW_BASE_URL="https://raw.githubusercontent.com/${SOURCE_REPO}/${BRANCH}/packages/${PKG_DIR}"


# The per-app temp file is removed on every explicit exit path below; the trap
# covers aborts between mktemp and those paths (set -e on touch/cp/heredoc).
trap 'rm -f "${tmp:-}"' EXIT

for app in "${APPS[@]}"; do
if [[ "$INDEX_MODE" == "true" ]]; then
src_file="${DEST_DIR%/}/${app}/_include/_index.md"
Expand All @@ -97,6 +101,24 @@ for app in "${APPS[@]}"; do
fi
fi

readme_url="${RAW_BASE_URL}/${app}/README.md"
echo "Processing $app..."

tmp=$(mktemp)
if ! curl -fsSL --compressed --retry 3 "$readme_url" \
| sed '1s/\xEF\xBB\xBF//' \
| awk 'NR==1 && /^#{1,2} / { next } { print }' > "$tmp"; then
rm -f "$tmp"
echo "Error: failed to fetch README for $app from $readme_url" >&2
exit 1
fi

if [[ ! -s "$tmp" ]]; then
rm -f "$tmp"
echo "Error: fetched empty README for $app from $readme_url" >&2
exit 1
fi

# Ensure template exists (touch if missing)
[[ -f "$src_file" ]] || touch "$src_file"

Expand All @@ -114,15 +136,8 @@ source: https://github.com/${SOURCE_REPO}/blob/${SOURCE_REF}/packages/${PKG_DIR}

EOF

readme_url="${RAW_BASE_URL}/${app}/README.md"
echo "Processing $app..."

if curl -fsSL --compressed "$readme_url" \
| sed '1s/\xEF\xBB\xBF//' \
| awk 'NR==1 && /^#{1,2} / { next } { print }' >> "$dest_file"; then
echo "✓ Appended README for $app -> $dest_file"
else
echo "⚠️ Failed to fetch README for $app" >&2
fi
cat "$tmp" >> "$dest_file"
rm -f "$tmp"
echo "✓ Appended README for $app -> $dest_file"

done
done