From 595bbea16033cfcd4b0c33d73e4521d999103743 Mon Sep 17 00:00:00 2001 From: Daniel Gyorgy Date: Fri, 6 Jun 2025 13:13:53 +0200 Subject: [PATCH 1/3] Add doc for deprecation of update command --- .../porch/user-guides/deprecation-of-update.md | 17 +++++++++++++++++ .../porch/user-guides/porchctl-cli-guide.md | 3 ++- 2 files changed, 19 insertions(+), 1 deletion(-) create mode 100644 content/en/docs/porch/user-guides/deprecation-of-update.md diff --git a/content/en/docs/porch/user-guides/deprecation-of-update.md b/content/en/docs/porch/user-guides/deprecation-of-update.md new file mode 100644 index 00000000..a157580c --- /dev/null +++ b/content/en/docs/porch/user-guides/deprecation-of-update.md @@ -0,0 +1,17 @@ +--- +title: "Deprecation of update" +type: docs +weight: 4 +description: "" +--- + +## 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 represents. +For more details, see: https://github.com/nephio-project/nephio/issues/892 + +## 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. +For more details, see: https://github.com/nephio-project/porch/pull/252 \ No newline at end of file diff --git a/content/en/docs/porch/user-guides/porchctl-cli-guide.md b/content/en/docs/porch/user-guides/porchctl-cli-guide.md index d5424a7d..95ac9c66 100644 --- a/content/en/docs/porch/user-guides/porchctl-cli-guide.md +++ b/content/en/docs/porch/user-guides/porchctl-cli-guide.md @@ -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.md) | +| `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 From 29b5f9ccb19c53524e974ef82ed07c7d3b137801 Mon Sep 17 00:00:00 2001 From: Daniel Gyorgy Date: Tue, 10 Jun 2025 10:15:59 +0200 Subject: [PATCH 2/3] move deprecation into porchctl cli-guide --- .../porch/user-guides/deprecation-of-update.md | 17 ----------------- .../porch/user-guides/porchctl-cli-guide.md | 17 +++++++++++++++-- 2 files changed, 15 insertions(+), 19 deletions(-) delete mode 100644 content/en/docs/porch/user-guides/deprecation-of-update.md diff --git a/content/en/docs/porch/user-guides/deprecation-of-update.md b/content/en/docs/porch/user-guides/deprecation-of-update.md deleted file mode 100644 index a157580c..00000000 --- a/content/en/docs/porch/user-guides/deprecation-of-update.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Deprecation of update" -type: docs -weight: 4 -description: "" ---- - -## 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 represents. -For more details, see: https://github.com/nephio-project/nephio/issues/892 - -## 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. -For more details, see: https://github.com/nephio-project/porch/pull/252 \ No newline at end of file diff --git a/content/en/docs/porch/user-guides/porchctl-cli-guide.md b/content/en/docs/porch/user-guides/porchctl-cli-guide.md index 95ac9c66..8d3f8fc0 100644 --- a/content/en/docs/porch/user-guides/porchctl-cli-guide.md +++ b/content/en/docs/porch/user-guides/porchctl-cli-guide.md @@ -49,7 +49,7 @@ 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` | Deprecated, please use the upgrade functionality instead. See: [Deprecation of update](deprecation-of-update.md) | +| `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 @@ -479,4 +479,17 @@ 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. \ No newline at end of file +proposal was approved is now in _Published_ state. + +## Deprecation of update + +### 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 represents. +For more details, see: https://github.com/nephio-project/nephio/issues/892 + +### 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. +For more details, see: https://github.com/nephio-project/porch/pull/252 \ No newline at end of file From 5865eaac2a0b86f176a0cb7a96f2a2a8421365d3 Mon Sep 17 00:00:00 2001 From: Daniel Gyorgy Date: Mon, 1 Sep 2025 18:15:37 +0200 Subject: [PATCH 3/3] fix review comments --- .../porch/user-guides/porchctl-cli-guide.md | 35 ++++++++++++++++--- 1 file changed, 30 insertions(+), 5 deletions(-) diff --git a/content/en/docs/porch/user-guides/porchctl-cli-guide.md b/content/en/docs/porch/user-guides/porchctl-cli-guide.md index 8d3f8fc0..a2b0c343 100644 --- a/content/en/docs/porch/user-guides/porchctl-cli-guide.md +++ b/content/en/docs/porch/user-guides/porchctl-cli-guide.md @@ -485,11 +485,36 @@ proposal was approved is now in _Published_ state. ### 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 represents. -For more details, see: https://github.com/nephio-project/nephio/issues/892 +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 +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. -For more details, see: https://github.com/nephio-project/porch/pull/252 \ No newline at end of file +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 \ No newline at end of file