feat(hack): generate docs from a pre-tag ref and fail loudly on fetch errors by myasnikovdaniil · Pull Request #631 · cozystack/website

myasnikovdaniil · 2026-07-24T14:31:09Z

What this PR does

Today make update-all RELEASE_TAG=vX.Y.Z can fetch content only from a ref named exactly like the release tag: the Makefile pins BRANCH := $(RELEASE_TAG), and every fetch goes to raw.githubusercontent.com/cozystack/cozystack/${BRANCH}/.... That forces docs generation to wait until the final tag exists — which is why the docs PR can only be opened after the release is already public. The upcoming promote-flow change in cozystack/cozystack wants to open this PR at promote time, before the stable tag is cut, generating from the digest-pinned release-X.Y.Z staging branch.

Two changes:

Makefile: new FETCH_REF ?= $(BRANCH) — the ref content is fetched from. It defaults to BRANCH (which stays pinned to RELEASE_TAG when set), so every existing invocation, including the current tags.yaml one, behaves byte-identically. Passing FETCH_REF=<staging-branch|rc-tag|sha> fetches content from that ref while version routing (DOC_VERSION, release-next, update-versions gating) still keys on RELEASE_TAG. The six update_apps.sh/update_versions.sh invocations now pass --branch "$(FETCH_REF)"; show-target echoes it.
hack/update_apps.sh: fail loudly instead of stubbing. Previously the script rewrote the destination doc (template copy + autogenerated notice) before fetching, and a failed fetch only printed a warning and continued with exit 0 — so a bad ref or a transient raw.githubusercontent error produced stub docs indistinguishable from a real update, which could be committed and merged. Now the README is fetched into a temp file first (curl --retry 3, BOM strip and heading drop unchanged); any fetch failure or empty body exits non-zero naming the app and URL, leaving existing docs byte-identical. A trap cleans the temp file on non-fetch error paths too.

Intended strictness worth acking in review: make update-all against an older tag whose tree lacks a currently-listed app now fails the docs job instead of committing a stub for that app. That couples the app roster to the fetched ref, deliberately — a stub merged into version docs is worse than a red job.

Deliberately out of scope: the manual template-* targets (fill_templates.sh) keep using $(BRANCH) and their soft-fail behavior; they are not part of the automated release path.

Verification

make show-target in all modes: legacy BRANCH=... RELEASE_TAG=... resolves FETCH_REF to the tag (byte-identical behavior), FETCH_REF=release-1.6.0-rc.4 RELEASE_TAG=v1.6.0 keeps routing on the tag while fetching from the staging ref, plain no-var runs stay on main. Live positive run: update_apps.sh --branch v1.6.0 produces real (non-stub) docs for all apps. Live negative run: --branch this-ref-does-not-exist exits 1 with the app and URL named and the destination tree byte-identical. Empty-body guard exercised. make update-all RELEASE_TAG=v1.6.0 FETCH_REF=v1.6.0 passes end-to-end; bash -n clean.

Summary by CodeRabbit

New Features
- Added configurable fetch references for documentation and update workflows.
- Added fetch-reference details to diagnostic output.
Bug Fixes
- Improved README retrieval reliability with automatic retries.
- Prevented incomplete or empty content from being written to documentation.
- Update scripts now report fetch failures clearly and stop when errors occur.

ghost · 2026-07-24T14:31:13Z

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

ghost · 2026-07-24T14:31:15Z

✅ Deploy Preview for cozystack ready!

Name	Link
🔨 Latest commit	`cd81a65`
🔍 Latest deploy log	https://app.netlify.com/projects/cozystack/deploys/6a69ddf2283f9c00072c6f8f
😎 Deploy Preview	https://deploy-preview-631--cozystack.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

ghost · 2026-07-24T14:31:19Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 68d8aa8b-67fa-4e0b-b944-df826c240eac

📥 Commits

Reviewing files that changed from the base of the PR and between c9bb53d and cd81a65.

📒 Files selected for processing (2)

Makefile
hack/update_apps.sh

📝 Walkthrough

Walkthrough

The Makefile adds an overrideable FETCH_REF for documentation updates. App README generation now downloads into temporary files with retries, validates content, cleans up on exit, and fails on fetch or empty-content errors before appending results.

Changes

Documentation fetch pipeline

Layer / File(s)	Summary
Overrideable documentation fetch ref `Makefile`	Defines `FETCH_REF`, uses it for app and next-version documentation updates, and displays it in `show-target`.
Temporary app README processing `hack/update_apps.sh`	Downloads and processes each README in a temporary file, retries curl requests, validates non-empty output, cleans up on failure, and appends successful content.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: kvaps, lllamnyp, tym83

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/prerelease-fetch-ref

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

ghost · 2026-07-27T06:10:47Z

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

ghost

LGTM — no blockers.

Fail-loud on fetch error verified across all branches: set -euo pipefail + curl -f + if ! ... wrapper + empty-$tmp guard, with pipefail propagating curl's exit through sed/awk. Happy-path output is byte-identical to before (only --retry 3 added), and template/notice writes now happen strictly after both guards, so a fetch failure can no longer publish an empty stub. All 6 call sites switched to $(FETCH_REF); template-* targets deliberately kept on $(BRANCH).

Non-blocking notes:

hack/update_apps.sh:116 — the [[ ! -s "$tmp" ]] guard treats a README that is a single H1/H2 line as failure (awk at :110 drops the first heading line → empty output → the whole docs job fails). Unrealistic for real app READMEs, but a behavioral edge distinct from the "empty body" case in the description.
hack/update_apps.sh:76 — shellcheck SC2034: SRC_DIR unused (pre-existing).
No automated regression test for the fail-loud behavior; relies on the manual runs documented in the PR body (consistent with hack/ having no test harness).

… 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]>

myasnikovdaniil mentioned this pull request Jul 24, 2026

ci(release): move release validation to rc time — e2e lane, changelog button, promote gate, docs at promote cozystack/cozystack#3449

Merged

myasnikovdaniil marked this pull request as ready for review July 27, 2026 06:10

myasnikovdaniil requested review from Andrei Kvapil (kvaps) and Timofei Larkin (lllamnyp) as code owners July 27, 2026 06:10

IvanHunters approved these changes Jul 27, 2026

View reviewed changes

myasnikovdaniil force-pushed the feat/prerelease-fetch-ref branch from 08f1200 to cd81a65 Compare July 29, 2026 11:03

myasnikovdaniil requested a review from Timur Tukaev (tym83) as a code owner July 29, 2026 11:03

myasnikovdaniil merged commit a22a03a into main Jul 29, 2026

myasnikovdaniil deleted the feat/prerelease-fetch-ref branch July 29, 2026 11:03

Navigation Menu

Repository navigation

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

feat(hack): generate docs from a pre-tag ref and fail loudly on fetch errors#631
myasnikovdaniil merged 1 commit into
mainfrom
feat/prerelease-fetch-ref

myasnikovdaniil commented Jul 24, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

ghost commented Jul 24, 2026

Uh oh!

ghost commented Jul 24, 2026 •

edited by netlify Bot

Loading

Uh oh!

ghost commented Jul 24, 2026 •

edited by coderabbitai Bot

Loading

Review failed

Walkthrough

Changes

Uh oh!

ghost commented Jul 27, 2026

Uh oh!

ghost left a comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

myasnikovdaniil commented Jul 24, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does

Verification

Summary by CodeRabbit

Uh oh!

ghost commented Jul 24, 2026

Uh oh!

ghost commented Jul 24, 2026 • edited by netlify Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cozystack ready!

Uh oh!

ghost commented Jul 24, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Uh oh!

ghost commented Jul 27, 2026

Uh oh!

ghost left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

myasnikovdaniil commented Jul 24, 2026 •

edited by coderabbitai Bot

Loading

ghost commented Jul 24, 2026 •

edited by netlify Bot

Loading

ghost commented Jul 24, 2026 •

edited by coderabbitai Bot

Loading