docs: document the project release lifecycle#760
Open
VajiraPrabuddhaka wants to merge 1 commit into
Open
Conversation
Contributor
📝 WalkthroughWalkthroughThe documentation introduces the ProjectType, ProjectRelease, and ProjectReleaseBinding lifecycle, adds authoring and developer deployment guides, expands Project and API references, and links the new pages into the Docusaurus sidebars. ChangesProject release documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related issues
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/reference/api/runtime/projectrelease.md (1)
1-118: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winFormat both API reference pages before merging.
The deployment pipeline reports Prettier formatting failures in these newly added files. Run Prettier on both files and rerun the formatting check.
docs/reference/api/runtime/projectrelease.md#L1-L118: apply the repository’s Prettier formatting.docs/reference/api/platform/projectreleasebinding.md#L1-L154: apply the repository’s Prettier formatting.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/reference/api/runtime/projectrelease.md` around lines 1 - 118, Apply the repository’s Prettier formatting to docs/reference/api/runtime/projectrelease.md (lines 1-118) and docs/reference/api/platform/projectreleasebinding.md (lines 1-154), then rerun the formatting check to verify both API reference pages pass.Source: Pipeline failures
🧹 Nitpick comments (1)
docs/developer-guide/deploying-applications/project-releases.md (1)
144-144: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsistency of the cell namespace placeholder format.
In
project-types.md(lines 18, 196), the cell namespace format is documented asdp-{ns}-{project}-{env}-{hash}. Here, it is written asdp-{namespace}-{project}-{environment}-{hash}. Consider using a consistent format across the documentation pages to prevent confusion.📝 Proposed fix
-The binding owns the project's data-plane namespace for its environment (named `dp-{namespace}-{project}-{environment}-{hash}` and surfaced on `status.namespace`). It creates the namespace, applies the resources rendered from the project type, and reports readiness through conditions: +The binding owns the project's data-plane namespace for its environment (named `dp-{ns}-{project}-{env}-{hash}` and surfaced on `status.namespace`). It creates the namespace, applies the resources rendered from the project type, and reports readiness through conditions:🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/developer-guide/deploying-applications/project-releases.md` at line 144, Update the cell namespace placeholder in the deploying applications documentation to use the same abbreviated format as project-types.md: dp-{ns}-{project}-{env}-{hash}. Keep the surrounding description and status.namespace reference unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/concepts/platform-abstractions.md`:
- Around line 150-152: Update the ProjectReleaseBinding documentation to state
that environmentConfigs are validated against the inlined type schema from the
pinned ProjectRelease snapshot, not the live ProjectType schema, so validation
remains fixed for existing bindings.
In `@docs/platform-engineer-guide/project-types.md`:
- Around line 254-258: Normalize the Markdown table formatting in the syntax
table, including column spacing and alignment, to match the repository’s
Prettier output. Verify the change by running the repository’s Prettier check.
- Around line 161-163: Update the Parameters documentation to state that
Project.spec.parameters is required and immutable, removing the claim that
changing it creates a new release. Document the supported workflow for changing
parameters, including creating a new Project or using the established
replacement/versioning process, while keeping the EnvironmentConfigs guidance
unchanged.
In `@docs/reference/api/platform/projectreleasebinding.md`:
- Around line 38-39: Update the projectRelease field description in the API
reference to clarify that an unset binding remains pending only until a latest
release exists; once available, the Project controller automatically populates
spec.projectRelease with that release, while it remains pending when no release
exists.
---
Outside diff comments:
In `@docs/reference/api/runtime/projectrelease.md`:
- Around line 1-118: Apply the repository’s Prettier formatting to
docs/reference/api/runtime/projectrelease.md (lines 1-118) and
docs/reference/api/platform/projectreleasebinding.md (lines 1-154), then rerun
the formatting check to verify both API reference pages pass.
---
Nitpick comments:
In `@docs/developer-guide/deploying-applications/project-releases.md`:
- Line 144: Update the cell namespace placeholder in the deploying applications
documentation to use the same abbreviated format as project-types.md:
dp-{ns}-{project}-{env}-{hash}. Keep the surrounding description and
status.namespace reference unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 5d72a7cd-f280-4c2c-bf2c-9bafc3b47aa0
📒 Files selected for processing (13)
docs/concepts/developer-abstractions.mddocs/concepts/platform-abstractions.mddocs/concepts/resource-relationships.mddocs/concepts/runtime-model.mddocs/developer-guide/deploying-applications/project-releases.mddocs/developer-guide/projects-and-components/creating-a-project.mddocs/platform-engineer-guide/project-types.mddocs/reference/api/application/project.mddocs/reference/api/platform/clusterprojecttype.mddocs/reference/api/platform/projectreleasebinding.mddocs/reference/api/platform/projecttype.mddocs/reference/api/runtime/projectrelease.mdsidebars.ts
Comment on lines
+150
to
+152
| Like the other bindings, a ProjectReleaseBinding carries per-environment configuration. Values supplied through its | ||
| `environmentConfigs` are validated against the schema declared on the project type, allowing the same release to run | ||
| with different quotas or policies in each environment while the snapshot itself remains unchanged. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Document validation against the pinned release snapshot.
ProjectReleaseBinding must validate environmentConfigs against the inlined type schema in its pinned ProjectRelease. Referring to the live ProjectType suggests later ProjectType edits can change validation for an existing binding.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/concepts/platform-abstractions.md` around lines 150 - 152, Update the
ProjectReleaseBinding documentation to state that environmentConfigs are
validated against the inlined type schema from the pinned ProjectRelease
snapshot, not the live ProjectType schema, so validation remains fixed for
existing bindings.
- Add the Authoring ProjectTypes platform engineer guide covering the namespace mandate, schemas, CEL validations, and the template surface - Add the Project Releases developer guide covering how releases are cut, client-created bindings, promotion, rollback, and conditions - Add API reference pages for ProjectType, ClusterProjectType, ProjectRelease, and ProjectReleaseBinding - Extend the concepts pages with the project-level release chain and the cell-namespace ownership model - Update the Project API reference and Creating a Project guide for the required, immutable spec.type and spec.parameters - Register the new pages in the sidebar Part of openchoreo/openchoreo#3808 Signed-off-by: VajiraPrabuddhaka <vajiraprabuddhaka@gmail.com>
VajiraPrabuddhaka
force-pushed
the
project-release-docs
branch
from
July 15, 2026 10:50
d8dd29e to
d20a7b4
Compare
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/platform-engineer-guide/project-types.md`:
- Around line 161-163: Align all listed documentation sites with the immutable
Project.spec.parameters contract: in
docs/platform-engineer-guide/project-types.md:161-163 and :228-228,
docs/developer-guide/deploying-applications/project-releases.md:53-57,
docs/concepts/platform-abstractions.md:304-306,
docs/concepts/resource-relationships.md:150-153, and
docs/reference/api/runtime/projectrelease.md:12 and :103-107, state that
ProjectType snapshot changes create ProjectReleases, remove claims that
parameter edits trigger releases, and document the supported
replacement/versioning workflow for changed parameters while preserving the
distinction that existing releases remain unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 9f81d95c-6334-4b45-a8c6-9fca13a71f26
📒 Files selected for processing (13)
docs/concepts/developer-abstractions.mddocs/concepts/platform-abstractions.mddocs/concepts/resource-relationships.mddocs/concepts/runtime-model.mddocs/developer-guide/deploying-applications/project-releases.mddocs/developer-guide/projects-and-components/creating-a-project.mddocs/platform-engineer-guide/project-types.mddocs/reference/api/application/project.mddocs/reference/api/platform/clusterprojecttype.mddocs/reference/api/platform/projectreleasebinding.mddocs/reference/api/platform/projecttype.mddocs/reference/api/runtime/projectrelease.mdsidebars.ts
🚧 Files skipped from review as they are similar to previous changes (7)
- docs/reference/api/platform/clusterprojecttype.md
- docs/reference/api/platform/projecttype.md
- docs/concepts/runtime-model.md
- docs/developer-guide/projects-and-components/creating-a-project.md
- docs/concepts/developer-abstractions.md
- docs/reference/api/application/project.md
- sidebars.ts
Comment on lines
+161
to
+163
| **Parameters** capture values supplied by the project author on `Project.spec.parameters`. They are validated against the `parameters` schema and inlined into every ProjectRelease snapshot, so the same values apply wherever that release is deployed. Changing a parameter on the Project cuts a new release; existing releases are never modified. | ||
|
|
||
| **EnvironmentConfigs** capture per-environment values supplied on `ProjectReleaseBinding.spec.environmentConfigs`. They are validated against the schema on the pinned release by the binding controller, and validation failures surface through the binding's `status.conditions`. Because they live on the binding, the same release deployed to dev and production can use different quotas, labels, or feature flips while the snapshot itself is unchanged. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Align all release documentation with immutable project parameters.
The documentation consistently claims that editing Project.spec.parameters creates a new ProjectRelease, but that field is required to be immutable. State that ProjectType snapshot changes create releases, and document the supported replacement/versioning workflow for changed parameters.
docs/platform-engineer-guide/project-types.md#L161-L163: remove the parameter-change release trigger and explain the immutable parameter contract.docs/platform-engineer-guide/project-types.md#L228-L228: remove the duplicate claim that parameter changes create releases.docs/developer-guide/deploying-applications/project-releases.md#L53-L57: remove parameter edits from the automatic release triggers.docs/concepts/platform-abstractions.md#L304-L306: describe only ProjectType changes as producing later snapshots.docs/concepts/resource-relationships.md#L150-L153: update the ProjectRelease lifecycle description.docs/reference/api/runtime/projectrelease.md#L12-L12: correct the controller behavior summary.docs/reference/api/runtime/projectrelease.md#L103-L107: correct the immutability and lifecycle bullets.
📍 Affects 5 files
docs/platform-engineer-guide/project-types.md#L161-L163(this comment)docs/platform-engineer-guide/project-types.md#L228-L228docs/developer-guide/deploying-applications/project-releases.md#L53-L57docs/concepts/platform-abstractions.md#L304-L306docs/concepts/resource-relationships.md#L150-L153docs/reference/api/runtime/projectrelease.md#L12-L12docs/reference/api/runtime/projectrelease.md#L103-L107
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/platform-engineer-guide/project-types.md` around lines 161 - 163, Align
all listed documentation sites with the immutable Project.spec.parameters
contract: in docs/platform-engineer-guide/project-types.md:161-163 and :228-228,
docs/developer-guide/deploying-applications/project-releases.md:53-57,
docs/concepts/platform-abstractions.md:304-306,
docs/concepts/resource-relationships.md:150-153, and
docs/reference/api/runtime/projectrelease.md:12 and :103-107, state that
ProjectType snapshot changes create ProjectReleases, remove claims that
parameter edits trigger releases, and document the supported
replacement/versioning workflow for changed parameters while preserving the
distinction that existing releases remain unchanged.
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.
Purpose
Documents the project release lifecycle introduced in openchoreo/openchoreo#3564 (
ProjectType,ClusterProjectType,ProjectRelease,ProjectReleaseBinding, and the extendedProjectwithspec.type/spec.parameters) so platform engineers and developers can onboard end-to-end.Follows the multi-surface treatment used for the resource abstractions docs (#644): concepts amended in place, one guide per audience, and per-CRD API reference pages.
Approach
platform-engineer-guide/project-types.md): authoring (Cluster)ProjectTypes, the cell-namespace mandate (${metadata.namespace},NamespaceMissing), parameters / environmentConfigs schemas, CEL validations, the template CEL surface, andincludeWhen/forEachdeveloper-guide/deploying-applications/project-releases.md): settingProject.spec.typeandparameters, how releases are auto-cut as<project>-<hash>, client-created bindings with one-time pin seeding, promotion viaocc project deploy --to/ Backstage / kubectl / GitOps, rollback, and binding conditionsProjectType,ClusterProjectType,ProjectReleaseBinding(platform) andProjectRelease(runtime, with Immutability and Lifecycle sections mirroringResourceRelease)platform-abstractions/developer-abstractions/resource-relationships, and the explicit cell-namespace ownership model inruntime-modelProjectAPI reference and the Creating a Project guide now cover the required, immutablespec.type,spec.parameters,status.latestRelease, andocc project scaffoldsidebars.tsThe docs describe the shipped v1 behavior only:
ProjectReleasesnapshots the type and parameters (no component/resource release pinning), andProjectReleaseBindingowns the cell namespace and applies the project-type resources (no fan-out).Related Issues
Resolves openchoreo/openchoreo#3808
Part of epic openchoreo/openchoreo#3564
Checklist
sidebars.tsif adding a new documentation pagenpm run startto preview the changes locallynpm run buildto ensure the build passes without errorsRemarks
While verifying the deletion flow against the controller code: the project cleanup finalizer removes the project's Components, Resources, and ProjectReleaseBindings, but does not GC ProjectReleases (the Resource finalizer does GC its ResourceReleases). The Lifecycle section is worded to match the shipped behavior; if the asymmetry is unintentional it may deserve an upstream issue.