docs: document the project release lifecycle#760
Merged
VajiraPrabuddhaka merged 1 commit intoJul 24, 2026
Conversation
Contributor
|
Warning Review limit reached
Next review available in: 43 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (13)
📝 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
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
VajiraPrabuddhaka
force-pushed
the
project-release-docs
branch
from
July 24, 2026 11:29
d20a7b4 to
8c413a7
Compare
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
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/platform/clusterprojecttype.md (1)
1-123: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winFix the Prettier formatting failure before merging.
CI reports
Prettier --checkfailure for this file. Run the repository’s formatter and commit the resulting Markdown changes:npx prettier --write docs/reference/api/platform/clusterprojecttype.md🤖 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/platform/clusterprojecttype.md` around lines 1 - 123, Run Prettier on the ClusterProjectType API reference Markdown file and commit the formatter’s resulting changes, preserving the documented content.Source: Pipeline failures
🤖 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 254-258: Run Prettier to normalize Markdown formatting in
docs/platform-engineer-guide/project-types.md lines 254-258,
docs/developer-guide/deploying-applications/project-releases.md lines 1-168,
docs/reference/api/platform/projectreleasebinding.md lines 34-39, and
docs/reference/api/runtime/projectrelease.md lines 34-40; preserve the
documented content while applying the formatter’s table and document layout.
---
Outside diff comments:
In `@docs/reference/api/platform/clusterprojecttype.md`:
- Around line 1-123: Run Prettier on the ClusterProjectType API reference
Markdown file and commit the formatter’s resulting changes, preserving the
documented content.
🪄 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 Plus
Run ID: 4ead3e60-ff8a-41bd-9d3e-660e236422c9
📒 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 (6)
- docs/concepts/developer-abstractions.md
- docs/developer-guide/projects-and-components/creating-a-project.md
- docs/reference/api/application/project.md
- sidebars.ts
- docs/concepts/runtime-model.md
- docs/reference/api/platform/projecttype.md
VajiraPrabuddhaka
force-pushed
the
project-release-docs
branch
from
July 24, 2026 11:33
8c413a7 to
cd8d94e
Compare
- 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 24, 2026 11:45
cd8d94e to
b46afb6
Compare
mevan-karu
approved these changes
Jul 24, 2026
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.
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.