fix(docs): stop autoupdate PRs from rewriting source URLs every run#516
Open
myasnikovdaniil wants to merge 3 commits intomainfrom
Open
fix(docs): stop autoupdate PRs from rewriting source URLs every run#516myasnikovdaniil wants to merge 3 commits intomainfrom
myasnikovdaniil wants to merge 3 commits intomainfrom
Conversation
`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 <myasnikovdaniil2001@gmail.com>
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 <myasnikovdaniil2001@gmail.com>
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (27)
📝 WalkthroughWalkthroughThe PR decouples fetch branch control from autogenerated documentation source references. The Makefile defines a SOURCE_REF variable mapped from DOC_VERSION, the shell script accepts ChangesDocumentation Source Reference Decoupling
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces a SOURCE_REF variable to decouple the Git reference used for fetching content from the one displayed in the "source" URL of generated documentation. This change ensures that documentation URLs remain stable across patch releases. The Makefile and hack/update_apps.sh script have been updated to support this new parameter, and various documentation files were updated to use the correct release reference. I have no feedback to provide.
Resolve Makefile conflict: combine main's `next/`-trunk routing (yq-based DOC_VERSION resolution + init-next/release-next/show-target targets) with this branch's stable SOURCE_REF block. The SOURCE_REF mapping is extended to cover the new `next` value of DOC_VERSION introduced by main: v0 → main (legacy bucket) next → main (trunk tracks upstream main) vX.Y → release-X.Y (long-lived branch for that minor) `update-*` targets keep passing `--source-ref "$(SOURCE_REF)"` so the displayed source URL stays stable across patch releases of the same minor, while BRANCH continues to pin fetches to the exact tag. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
source:URL ref in synced docs from thefetch branch so patch releases and the daily cron stop flipping it
on every run.
v1.0/source URLs (which stampedrelease-1.2.1)to
release-1.0.Context
Auto-update PRs from this repo's daily cron, and from
cozystack/cozystack's releasetags.yaml, were touching ~30 files per run for nothing more than swapping thesource:line betweenmain,release-1.X, andvX.Y.Z. The fetch ref and the displayed ref were the same value.hack/update_apps.shnow accepts an optional--source-ref REF(defaults to--branchfor backward compat). The Makefile derives a stableSOURCE_REFfromDOC_VERSION:DOC_VERSIONSOURCE_REFv0main(legacy, preserves current state)vX.Y(X≥1)release-X.YFetch still uses
BRANCH(the exact tag for reproducibility).Caller compatibility
cozystack/cozystacktags.yaml:make update-all BRANCH=… RELEASE_TAG=…— unchanged.update-managed-apps.yaml:make update-all DOC_VERSION=…— unchanged.hack/update_apps.shruns without--source-ref: falls back to--branch(no behavior change).fill_templates.shdoesn't touchsource:URLs, so no changes there.Test plan
make -n update-apps→--source-ref release-1.2make -n update-apps RELEASE_TAG=v1.0.5→--source-ref release-1.0, fetch fromv1.0.5make -n update-apps RELEASE_TAG=v1.2.5→--source-ref release-1.2, fetch fromv1.2.5make -n update-apps RELEASE_TAG=v0.30.5→--source-ref main, fetch fromv0.30.5release-1.0README URLs used in v1.0 docs return 200--source-reffalls back to--branch(verified in temp dir)cozystack/cozystackrelease) should be small — touching only files whose upstream README content actually changed.Summary by CodeRabbit