Docs main placeholder pr concept#1026
Open
Catalin-Stratulat-Ericsson wants to merge 3 commits into
Open
Conversation
Signed-off-by: Catalin-Stratulat-Ericsson <catalin.stratulat@ericsson.com>
Signed-off-by: Catalin-Stratulat-Ericsson <catalin.stratulat@ericsson.com>
✅ Deploy Preview for kpt-porch ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds dedicated documentation for “placeholder package revisions” and updates the Concepts index to link to the new page.
Changes:
- Added a new concepts doc page describing placeholder package revision behavior, lifecycle, rollback semantics, and GitOps relationship
- Replaced the inline placeholder description in the concepts index with a relref link + shorter summary
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/content/en/docs/2_concepts/placeholder-package-revision.md | New doc page defining placeholder package revisions and explaining lifecycle/usage constraints |
| docs/content/en/docs/2_concepts/_index.md | Replaces long inline placeholder description with a link to the new dedicated doc page |
Catalin-Stratulat-Ericsson
added
the
documentation
nagygergo
reviewed
Jun 10, 2026
|
|
||
| Yes. The placeholder is **not immutable**. It can be deleted via `porchctl` like any other PackageRevision. This is useful during package cleanup (e.g. removing a package entirely from a repository). | ||
|
|
||
| Deleting the placeholder does **not** affect the underlying Git branch content. |
Contributor
There was a problem hiding this comment.
Is it not? I thought that deleting the placeholder removes it from the main branch.
Contributor
Author
There was a problem hiding this comment.
yes you are right. i was under the impression that the latest tag PR is what decides this and its removal means content in main is removed. tested and it is as you say the main is what dictates this. i will reformat
nagygergo
reviewed
Jun 10, 2026
|
|
||
| ## Restrictions | ||
|
|
||
| The placeholder cannot be used as a source for certain operations: |
Contributor
There was a problem hiding this comment.
Are these actually enforced?
Contributor
Author
There was a problem hiding this comment.
yes they are i believe i just checked them (at least at the cli level, unsure about api). Haven't checked upgrade yet but clone and copy seem fine
Copy:
catalin@E-5CG2302VDX:~/Nephio/2026/11-test/porch$ porchctl rpkg copy example-repository.demo-package.main --workspace=example-workspace-2 --namespace=example-namespace
Error: Internal error occurred: source revision may not be the placeholder package revision example-repository/example-repository.demo-package.mainClone:
catalin@E-5CG2302VDX:~/Nephio/2026/11-test/porch$ porchctl rpkg clone example-repository.demo-package.main demo-package-2 --repository=test-blueprints --workspace=example-workspace-2 --namespace=example-namespace
Error: Internal error occurred: source revision may not be the placeholder package revision example-repository/example-repository.demo-package.main
Contributor
There was a problem hiding this comment.
Yes - the checks are at the level of applying the tasks, so they cover the API as well.
nagygergo
reviewed
Jun 10, 2026
| | Subsequent revision published | Placeholder **updated** to new content | | ||
| | Published revision deleted | Placeholder **unchanged** (no rollback) | | ||
| | Placeholder itself deleted | Removed from Porch (Git branch unaffected) | | ||
| | New revision published after placeholder deletion | Placeholder **recreated** | |
Contributor
There was a problem hiding this comment.
created with contents of the new version
Contributor
Author
There was a problem hiding this comment.
will amend
efiacor
requested review from
efiacor,
kispaljr,
liamfallon and
mozesl-nokia
as code owners
|
liamfallon
reviewed
Jun 17, 2026
| * its naming comvention is `{repository-name}.{package-name}.{branch-name}`, where {branch-name} is the branch in Git | ||
| on which the package revision exists | ||
| * ***[Placeholder package revision]({{% relref "placeholder-package-revision" %}})***: A package revision that tracks | ||
| the content of a package's configured Git branch (typically `main`). It is created automatically when the first revision |
Contributor
There was a problem hiding this comment.
Suggested change
| the content of a package's configured Git branch (typically `main`). It is created automatically when the first revision | |
| the most recent content of a package in its repository. It is created automatically when the first revision |
| type: docs | ||
| weight: 4 | ||
| description: | | ||
| The placeholder package revision tracks the configured Git branch for a package. This page explains its behaviour, lifecycle interactions, and how it relates to GitOps workflows. |
Contributor
There was a problem hiding this comment.
Suggested change
| The placeholder package revision tracks the configured Git branch for a package. This page explains its behaviour, lifecycle interactions, and how it relates to GitOps workflows. | |
| The placeholder package revision tracks the most recent content of a package in its repository. This page explains its behaviour, lifecycle interactions, and how it relates to GitOps workflows. |
|
|
||
| ## Overview | ||
|
|
||
| The placeholder package revision is a special PackageRevision that Porch creates automatically to represent the state of a package on its configured Git branch. It acts as a "branch-tracking" reference, always reflecting the content of the most recently published revision. |
Contributor
There was a problem hiding this comment.
Suggested change
| The placeholder package revision is a special PackageRevision that Porch creates automatically to represent the state of a package on its configured Git branch. It acts as a "branch-tracking" reference, always reflecting the content of the most recently published revision. | |
| The placeholder package revision is a special PackageRevision that Porch creates automatically as a reference the latest released version of a package. It acts as a "branch-tracking" reference. The placeholder package revision points at the version of the package revision at the HEAD of the branch of the repository that the package revision is stored on. |
| | Naming convention | `{repository-name}.{package-name}.{branch-name}` | | ||
| | Lifecycle | `Published` | | ||
|
|
||
| There is always at most one placeholder package revision per package. |
Contributor
There was a problem hiding this comment.
Suggested change
| There is always at most one placeholder package revision per package. | |
| There is one and only one placeholder package revision per package. |
| 1. Publish v1 (revision 1): placeholder is **created** with v1's content | ||
| 2. Publish v2 (revision 2): placeholder is **updated** with v2's content | ||
|
|
||
| The placeholder **only moves forward** through explicit publish operations. |
Contributor
There was a problem hiding this comment.
Suggested change
| The placeholder **only moves forward** through explicit publish operations. | |
| The placeholder **only moves forward** on each explicit publish operations. |
|
|
||
| The placeholder **only moves forward** through explicit publish operations. | ||
|
|
||
| ## What Happens When a Revision Is Deleted? |
Contributor
There was a problem hiding this comment.
Suggested change
| ## What Happens When a Revision Is Deleted? | |
| ## What Happens When the Latest Package Revision Is Deleted? |
|
|
||
| ## What Happens When a Revision Is Deleted? | ||
|
|
||
| Deleting a published revision (even if it is the latest) does **not** cause the placeholder to roll back to a previous revision. The placeholder retains the content it had at the time of the last publish. |
Contributor
There was a problem hiding this comment.
Suggested change
| Deleting a published revision (even if it is the latest) does **not** cause the placeholder to roll back to a previous revision. The placeholder retains the content it had at the time of the last publish. | |
| Deleting the latest published package revision does **not** cause the placeholder to roll back to a previous revision. The placeholder retains the content it had at the time of the last publish. It still refers to the version of the Package Revision at the HEAD of the branch in git. |
|
|
||
| ## Relationship to GitOps | ||
|
|
||
| In a GitOps workflow, a reconciler (such as Flux or ArgoCD) watches a branch in Git for changes. The placeholder package revision corresponds directly to this branch. |
Contributor
There was a problem hiding this comment.
Suggested change
| In a GitOps workflow, a reconciler (such as Flux or ArgoCD) watches a branch in Git for changes. The placeholder package revision corresponds directly to this branch. | |
| In a GitOps workflow, a reconciler (such as Flux or ArgoCD) watches a branch in Git for changes. The placeholder package revision references this branch. |
| | First revision published | Placeholder **created** | | ||
| | Subsequent revision published | Placeholder **updated** to new content | | ||
| | Published revision deleted | Placeholder **unchanged** (no rollback) | | ||
| | Placeholder itself deleted | Removed from Porch (Git branch unaffected) | |
|
|
||
| ## Restrictions | ||
|
|
||
| The placeholder cannot be used as a source for certain operations: |
Contributor
There was a problem hiding this comment.
Yes - the checks are at the level of applying the tasks, so they cover the API as well.
|
|
||
| - **Clone**: cannot clone from a placeholder | ||
| - **Edit/Copy**: cannot edit or copy a placeholder | ||
| - **Upgrade**: cannot upgrade to or from a placeholder |
Contributor
There was a problem hiding this comment.
Suggested change
| - **Upgrade**: cannot upgrade to or from a placeholder | |
| - **Upgrade**: cannot upgrade a placeholder or use a placeholder as the target upstream of an upgrade |
(using a placeholder as the source upstream is already ruled out by not being able to clone a placeholder)
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
Adding concept for main/placeholder PackageRevision
Description
latest-1if the latest is deleted where main is pointing atRelated Issue(s)
Type of Change
Checklist
Testing Instructions (Optional)
Additional Notes (Optional)
AI Disclosure
If so, please describe how: