PackageRevision controller architecture docs#971
Open
efiacor wants to merge 5 commits into
Open
Conversation
efiacor
requested review from
Catalin-Stratulat-Ericsson,
JamesMcDermott,
aravindtga,
kushnaidu,
liamfallon,
lovesprung,
mozesl-nokia and
rendre-greyling
May 6, 2026 19:14
✅ Deploy Preview for porch ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
also no functionality section for this component like all the others even other controllers? was this intentional or just missed? |
lovesprung
reviewed
May 13, 2026
efiacor
marked this pull request as draft
May 15, 2026 07:27
efiacor
force-pushed
the
pr_ctr_docs_draft
branch
from
July 1, 2026 09:25
4098450 to
6e949f5
Compare
✅ Deploy Preview for kpt-porch ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
efiacor
marked this pull request as ready for review
July 1, 2026 09:27
dosubot
Bot
added
the
size:XXL
📄 Knowledge review✏️ Suggested updates1 page suggestion needs review.
|
Contributor
There was a problem hiding this comment.
Pull request overview
Adds draft architecture documentation for the v1alpha2 (CRD-based) PackageRevision controller and updates the docs site build/layout to better support versioned docs and navigation.
Changes:
- Adds new architecture + functionality docs for the PackageRevision controller and a new “Working with CRD-Based PackageRevisions” tutorial section.
- Updates architecture/overview/config docs to reflect the CRD-based orchestration path and controller responsibilities.
- Improves the docs site UX/build: version selector override, foldable + resizable sidebar, heading rendering changes, draft handling configs, and versioned docs build script tweaks.
Reviewed changes
Copilot reviewed 37 out of 37 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/build-versioned-docs.sh | Ensures consistent nav by copying key _index.md files from main into versioned builds. |
| README.md | Updates documentation link to the new site URL. |
| docs/README.md | Updates docs landing reference and rendered-site URL. |
| docs/layouts/partials/navbar-version-selector.html | Overrides Docsy version selector behavior for / links. |
| docs/layouts/partials/hooks/body-end.html | Adds client-side sidebar scroll/width persistence and resize behavior. |
| docs/layouts/_default/_markup/render-heading.html | Switches heading rendering to Docsy partial. |
| docs/content/en/docs/6_configuration_and_deployments/configurations/components/porch-controllers-config.md | Documents PR controller flags/env/prereqs and tuning guidance. |
| docs/content/en/docs/6_configuration_and_deployments/configurations/components/_index.md | Updates controllers component description to include PackageRevisions. |
| docs/content/en/docs/6_configuration_and_deployments/configurations/_index.md | Updates controllers config summary to include PR controller. |
| docs/content/en/docs/5_architecture_and_components/porch-apiserver/_index.md | Adjusts nav ordering (weight). |
| docs/content/en/docs/5_architecture_and_components/package-cache/_index.md | Adjusts nav ordering (weight). |
| docs/content/en/docs/5_architecture_and_components/function-runner/_index.md | Adjusts nav ordering (weight). |
| docs/content/en/docs/5_architecture_and_components/engine/_index.md | Adjusts nav ordering (weight). |
| docs/content/en/docs/5_architecture_and_components/controllers/repository-controller/interactions.md | Documents v1alpha2 CRD creation behavior and gating controls. |
| docs/content/en/docs/5_architecture_and_components/controllers/repository-controller/_index.md | Adds repository annotation explanation for v1alpha2 CRD-based management. |
| docs/content/en/docs/5_architecture_and_components/controllers/packagerevision-controller/interactions.md | New: component interaction model and end-to-end data flows. |
| docs/content/en/docs/5_architecture_and_components/controllers/packagerevision-controller/functionality/source-execution.md | New: source execution behaviors (init/clone/copy/upgrade). |
| docs/content/en/docs/5_architecture_and_components/controllers/packagerevision-controller/functionality/rendering.md | New: render triggers, concurrency limiting, stale render handling, status semantics. |
| docs/content/en/docs/5_architecture_and_components/controllers/packagerevision-controller/functionality/lifecycle-management.md | New: lifecycle transitions, revision labels, deletion gating/finalizers. |
| docs/content/en/docs/5_architecture_and_components/controllers/packagerevision-controller/functionality/_index.md | New: functionality section index/overview. |
| docs/content/en/docs/5_architecture_and_components/controllers/packagerevision-controller/design.md | New: internal controller design and SSA field manager partitioning. |
| docs/content/en/docs/5_architecture_and_components/controllers/packagerevision-controller/_index.md | New: controller overview and relationship to other components. |
| docs/content/en/docs/5_architecture_and_components/controllers/_index.md | Reorders and adds PR controller entry under Controllers. |
| docs/content/en/docs/5_architecture_and_components/_index.md | Reframes architecture around two orchestration paths (v1alpha1 vs v1alpha2). |
| docs/content/en/docs/4_tutorials_and_how-tos/working_with_crd_based_packagerevisions/differences.md | New: user-facing differences between aggregated API and CRD-based model. |
| docs/content/en/docs/4_tutorials_and_how-tos/working_with_crd_based_packagerevisions/creating-packages.md | New: kubectl-based workflow (create/push/render/publish/delete). |
| docs/content/en/docs/4_tutorials_and_how-tos/working_with_crd_based_packagerevisions/_index.md | New: enablement + prerequisites + next steps for CRD-based workflow. |
| docs/content/en/docs/4_tutorials_and_how-tos/_index.md | Adds entry point to the new v1alpha2 CRD-based tutorials. |
| docs/content/en/docs/12_contributing/docs-contribution/_index.md | Adds guidance for documenting unreleased features with Hugo drafts. |
| docs/content/en/docs/1_overview/_index.md | Updates high-level overview to reflect architecture direction and controllers. |
| docs/content/en/docs/_index.md | Updates docs landing page intro text. |
| docs/config/production.toml | Adds placeholder config to avoid Netlify config-merge warnings. |
| docs/config/development.toml | Enables buildDrafts for preview/development builds. |
| docs/config.toml | Adjusts markup behavior and enables foldable sidebar menu. |
| docs/assets/scss/_sidebar-toc.scss | Tweaks sidebar TOC sizing/positioning. |
| docs/assets/scss/_sidebar-left.scss | Makes left sidebar wider/resizable; updates version selector styling and scrolling behavior. |
| docs/assets/scss/_main.scss | Ensures main layout flexes correctly when sidebar is resized. |
efiacor
force-pushed
the
pr_ctr_docs_draft
branch
from
July 1, 2026 10:22
0411000 to
9b47d85
Compare
Contributor
Author
|
@lovesprung @Catalin-Stratulat-Ericsson |
efiacor
changed the title
2 tasks
Catalin-Stratulat-Ericsson
requested changes
Jul 20, 2026
Catalin-Stratulat-Ericsson
left a comment
Catalin-Stratulat-Ericsson
left a comment
Contributor
There was a problem hiding this comment.
looks great but just a few minor changes. also maybe a small addition to the porchctl section to explain the diff's between targeting v1alpha1 vs v1alpha2 with the old vs new arch.
Add v1alpha2 architecture documentation for the PackageRevision controller as Hugo draft pages. These render in deploy previews but are hidden from the production build. New pages: - deployment-modes.md: v1alpha1 vs v1alpha2 architecture comparison - packagerevision-controller/_index.md: controller overview - packagerevision-controller/design.md: internal design - packagerevision-controller/interactions.md: component interactions Also adds docs/config/development.toml (buildDrafts=true) and docs/config/production.toml so the existing Netlify build command picks up environment-specific settings.
Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>
Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>
Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>
Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>
efiacor
force-pushed
the
pr_ctr_docs_draft
branch
from
July 21, 2026 11:10
6f2d718 to
490a956
Compare
|
Catalin-Stratulat-Ericsson
approved these changes
Jul 22, 2026
Catalin-Stratulat-Ericsson
left a comment
Catalin-Stratulat-Ericsson
left a comment
Contributor
There was a problem hiding this comment.
good stuff 👍
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
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.
Title
PackageRevision controller architecture docs
Description
Add v1alpha2 architecture documentation for the PackageRevision controller.
New pages:
packagerevision-controller/_index.md: controller overview
packagerevision-controller/design.md: internal design
packagerevision-controller/interactions.md: component interactions
Why it’s needed: New docs
How it works: See above
Related Issue(s)
Type of Change
Checklist
Testing Instructions (Optional)
Additional Notes (Optional)
AI Disclosure
[X] I have used AI in the creation of this PR.