Repository navigation
build(docs): generate reference pages for Valkey, OpenSearch, Bucket, KubernetesNodes, ComputePlane and Gateway - #756
Merged
Conversation
A patch release of an older line runs `make update-all` with the same app lists against that line's tag and docs tree. An app added for a newer release has no README at the old tag, so `update_apps.sh` exits 1 on the 404 and the docs job fails. An app that does exist at the old tag but was never documented there gets an empty template touched into the old tree and a page without front matter. Treat the `_include/<app>.md` template as the roster: a version documents the apps it has a template for. An app without one is skipped with a warning before anything is fetched or written, so the lists can name every current app while older trees keep their own set. An app that has a template and whose README is missing at the ref still fails the job, as before. Assisted-By: LLM Signed-off-by: Myasnikov Daniil <[email protected]>
Valkey is new in v1.7; OpenSearch (since v1.2) and Bucket (since v1.0) are in the catalog but have no reference page in any docs version. Their READMEs are generated by cozyvalues-gen and in sync with values.yaml at v1.7.0-rc.1, so they go into APPS with front-matter templates in the trunk. `release-next` copies the templates into the new version tree and the promote run's `update-all` renders the pages from the release ref; generated pages are not committed by hand. Older lines have no template for these apps, so patch releases of them skip the apps instead of fetching a README that may not exist there or writing a page that version never had. Assisted-By: LLM Signed-off-by: Myasnikov Daniil <[email protected]>
From v1.7 a managed Kubernetes cluster gets its workers from KubernetesNodes resources: `nodeGroups` is gone from the kubernetes chart. The kubernetes-nodes README is generated by cozyvalues-gen and in sync with values.yaml at v1.7.0-rc.1, but no docs version renders it, so the pool options have no reference page. Render it as a page inside the Kubernetes section, next to the cluster reference in kubernetes/_index.md, from its own list so that it is a regular page rather than a second index section. The v1.6 tree has no template for it, so v1.6 patch releases skip it. Assisted-By: LLM Signed-off-by: Myasnikov Daniil <[email protected]>
ComputePlane is a tenant module new in v1.7 and Gateway has been one since v1.5; neither has a reference page in any docs version, so the ComputePlane values and Gateway's `tlsPassthroughListeners` have no reference. Both READMEs are generated by cozyvalues-gen and in sync with values.yaml at v1.7.0-rc.1, and both live under packages/extra like the other modules in SERVICES, so they go there with templates in the trunk. They are appended on a line of their own rather than on the SERVICES line, which sits next to the NETWORKING line and would conflict with any edit to it. Older lines have no template for them, so their patch releases skip both instead of writing pages that version never had. Assisted-By: LLM Signed-off-by: Myasnikov Daniil <[email protected]>
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configuration
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 |
myasnikovdaniil
marked this pull request as ready for review
October 16, 2026 09:36
myasnikovdaniil
requested review from
Andrei Kvapil (kvaps),
Timofei Larkin (lllamnyp) and
Timur Tukaev (tym83)
as code owners
October 16, 2026 09:36
IvanHunters
approved these changes
Oct 16, 2026
IvanHunters
left a comment
IvanHunters
left a comment
Contributor
There was a problem hiding this comment.
LGTM — approve.
Walked the hack/update_apps.sh change and verified the generation paths against the actual cozystack tree, not just the diff.
What I checked:
- All six new READMEs resolve at
v1.7.0-rc.1(the fetch ref the promote run uses):apps/{valkey,opensearch,bucket,kubernetes-nodes}andextra/{computeplane,gateway}all return 200, so promote won't 404. - The new
_includetemplates live only undernext/;v1.6andv1.5carry none of them, so the template-presence guard skips the new apps on a patch run of an older line instead of fetching a 404 or writing a front-matter-less page. - The guard runs on every invocation, so I checked it doesn't break existing output: the
kubernetesindex template (next|v1.6|v1.5/kubernetes/_include/_index.md) andmonitoring'sparameters.mdare all present, andhttp-cachekeeps its template innext/v1.6— a removed app still surfaces its 404 rather than being masked. The guard is template-driven, not blanket skip-on-404. kubernetes-nodesrenders flat (no--index) tokubernetes/kubernetes-nodes.md, path matches.- Front matter:
computeplane/gatewayomitweight, matching the other SERVICES templates; the new apps omitaliases, correct since they had no old URL scheme to redirect from. bash -nclean; shellcheck's only hit is the pre-existing SC2034 onSRC_DIR(untouched here). Live CI on the head is green (i18n-lint, DCO), Pages checks neutral.
One open question, which you already flagged: the bucket/gateway pages overlap with the hand-written object-storage/buckets.md and networking/gateway-api.md — maintainer's call whether to keep both.
Tested against main (merges cleanly).
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
2 participants
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.
Cozystack 1.7 adds Valkey and the ComputePlane module and moves worker pools to KubernetesNodes, while OpenSearch, Bucket and the tenant Gateway module never had a reference page. Their READMEs are generated by cozyvalues-gen and match
values.yamlat v1.7.0-rc.1, but none of them is in the Makefile lists, so 1.7 docs would ship without them.valkey,opensearchandbucketgo toAPPS(applications/)kubernetes-nodesgets its own list and renders askubernetes/kubernetes-nodes.mdin the Kubernetes sectioncomputeplaneandgatewaygo toSERVICESon a separateSERVICES +=line, because theSERVICESline is next toNETWORKINGand editing both would conflictEach app gets a front matter template in
next/.release-nextcopies templates intov1.7/and the promote run renders pages from the release ref, so no generated page is committed here.Patch releases of older lines run the same lists against their own tag. Valkey and ComputePlane have no README at v1.6 and v1.5, so
update_apps.shwould exit 1 on 404 and fail the docs job. For OpenSearch, Bucket, Gateway and KubernetesNodes the oldtouchfallback would write an empty template and a page without front matter into the old tree. Nowupdate_apps.shtreats the_include/<app>.mdtemplate as the list of apps a version documents: app without template is skipped with a warning before anything is fetched or written, app with template but missing README still fails as before. This covers what #728 does with its trunk-only list. I didn't reuse that list because the promote run skips it,release-nextregisters the new version beforeupdate-allroutes to it.Bucket and Gateway pages overlap with hand-written
object-storage/buckets.mdandnetworking/gateway-api.md. I wired them anyway, say if you want them out. The KubernetesNodes commit is separate and easy to drop.Checks: I replayed promote on a copy (
release-next, thenupdate-all RELEASE_TAG=v1.7.0 FETCH_REF=v1.7.0-rc.1), all six pages generate intov1.7/and Hugo 0.164.0 preview and production builds pass.update-allfor v1.6.5 and v1.5.5 passes with six skip warnings and adds no files, with main's script the v1.6 run fails on valkey 404. With http-cache still listed the v1.7.0 run still fails on its 404, so the guard doesn't hide a removed app. shellcheck reports nothing new and i18n checks pass.Both this PR and the HTTPCache one must land before the v1.7.0 promote run. They merge cleanly in any order, #728 can go after the 1.7 snapshot.