Skip to content

Documentation for #892 #236

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dgyorgy-nokia wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Documentation for #892 #236

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
595bbea
Add doc for deprecation of update command
dgyorgy-nokia Jun 6, 2025
29b5f9c
move deprecation into porchctl cli-guide
dgyorgy-nokia Jun 10, 2025
5865eaa
fix review comments
dgyorgy-nokia Sep 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 41 additions & 2 deletions content/en/docs/porch/user-guides/porchctl-cli-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,8 @@ The commands for administering package revisions are:
| `porchctl rpkg pull` | Pull the content of the package revision. |
| `porchctl rpkg push` | Push resources to a package revision. |
| `porchctl rpkg reject` | Reject a proposal to publish or delete a package revision. |
| `porchctl rpkg update` | Update a downstream package revision to a more recent revision of its upstream package. |
| `porchctl rpkg update` | Deprecated, please use the upgrade functionality instead. See: [Deprecation of update](#deprecation-of-update) |
| `porchctl rpkg upgrade` | Update a downstream package revision to a more recent revision of its upstream package using 3 way merge. |

## Using the porchctl CLI

Expand Down Expand Up @@ -478,4 +479,42 @@ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1
```

Observe that the rejected proposal returned the package revision back to _Draft_ lifecycle stage. The package whose
proposal was approved is now in _Published_ state.
proposal was approved is now in _Published_ state.

## Deprecation of update
Copy link
Collaborator

@efiacor efiacor Jun 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be in a separate document rather than a footnote here?

Copy link
Author

@dgyorgy-nokia dgyorgy-nokia Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought it fit best here.
Do you mean there should be a separate document for changes? (e.g. porch/deprecations/deprecation-of-update.md)

Copy link
Collaborator

@efiacor efiacor Nov 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I think this should prob go along side the pkg upgrade information somewhere.
ie. https://github.com/nephio-project/docs/pull/275/files#diff-c8dfd61e3415b700bf6f0634dbaa3d8df0fa865bba362ce6abc87993fc9541c1


### Motivation

The PackageRevision API object was meant to represent only metadata related to a package revision, while the contents
of the package revision (i.e. the YAML files) are meant to be exposed via a companion PackageRevisionResources object.
However PackageRevision's spec.tasks field contains all changes applied to the contents of the package revision in
the form of patches, thus the contents of the package are leaking into the object that supposed to represent only the
metadata. This implies that the PackageRevision can quickly grow bigger in size, than the contents of the package it
Copy link
Contributor

@CsatariGergely CsatariGergely Oct 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
metadata. This implies that the PackageRevision can quickly grow bigger in size, than the contents of the package it
metadata. This means that the PackageRevision could abruptly grow bigger in size, than the contents of the package it

represents.

### Solution

We have introduced a new first task type, called upgrade. When there is a need to update a downstream package revision
to a more up to date revision of its upstream package, do not store unnecessarily the diff's between the package
revisions. Instead, now we use a 3-way-merge operation, where the old upstream, new upstream and the local revision
changes are merged together. The introduced 3 way merge implementation is based on the kyaml's 3-way-merge solution.
With this approach, we can reduce the task list to only one element, also we can deprecate the Patch/Eval/Update task
types, since there will be no need for these. The remaining Init/Edit/Clone/Upgrade task can clearly identify the
origin of a PackageRevision.

### Example
porchctl rpkg upgrade repository.package.1 --namespace=porch-demo --revision=2 --workspace=2
This command upgrades the package `repository.package.1` to the second version (revision=2) of its parent package.
It then creates a new package `repository.package.2` with the workspace name specified in the command (workspace=2).
### Migration guide from `update` to `upgrade`
The `upgrade` command now internally handles the functionality previously provided by:
porchctl rpkg copy --replay-strategy=true
This eliminates the need for users to manually copy a cloned package. Additionally, the `upgrade` command operates on
approved packages.
#### Previous workflow:
porchctl rpkg copy repository.package-copy.2 --namespace=porch-demo --workspace=3 --replay-strategy=true
porchctl rpkg update --discover=upstream
porchctl rpkg update porch-test.subpackage-copy.3 --namespace=porch-demo --revision=2
#### New workflow:
porchctl rpkg upgrade --discover=upstream
porchctl rpkg upgrade porch-test.subpackage-copy.2 --namespace=porch-demo --revision=2 --workspace=3