From caeaa60163b427e9c448cae7dd88538e742a9594 Mon Sep 17 00:00:00 2001 From: lapentafd Date: Thu, 9 Oct 2025 15:57:07 +0100 Subject: [PATCH 1/6] rebase on main Signed-off-by: lapentafd --- .../user-guides/deprecation-of-update.md | 17 ++++++ .../porch/user-guides/porchctl-cli-guide.md | 59 ++++++++++++++----- 2 files changed, 62 insertions(+), 14 deletions(-) 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..3da8bb85 --- /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 6c4ffe15..8376ec58 100644 --- a/content/en/docs/porch/user-guides/porchctl-cli-guide.md +++ b/content/en/docs/porch/user-guides/porchctl-cli-guide.md @@ -35,20 +35,21 @@ The commands for administering repositories are: The commands for administering package revisions are: -| Command | Description | -| ------------------------------ | ------------------------------------------------------------------------------------------------ | -| `porchctl rpkg approve` | Approve a proposal to publish a package revision. | -| `porchctl rpkg clone` | Create a clone of an existing package revision. | -| `porchctl rpkg copy` | Create a new package revision from an existing one. | -| `porchctl rpkg del` | Delete a package revision. | -| `porchctl rpkg get` | List package revisions in registered repositories. | -| `porchctl rpkg init` | Initializes a new package revision in a repository. | -| `porchctl rpkg propose` | Propose that a package revision should be published. | -| `porchctl rpkg propose-delete` | Propose deletion of a published package revision. | -| `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 upgrade` | Update a downstream package revision to a more recent revision of its upstream package revision. | +| Command | Description | +| ------------------------------ | -------------------------------------------------------------------------------------------------------------- | +| `porchctl rpkg approve` | Approve a proposal to publish a package revision. | +| `porchctl rpkg clone` | Create a clone of an existing package revision. | +| `porchctl rpkg copy` | Create a new package revision from an existing one. | +| `porchctl rpkg del` | Delete a package revision. | +| `porchctl rpkg get` | List package revisions in registered repositories. | +| `porchctl rpkg init` | Initializes a new package in a repository. | +| `porchctl rpkg propose` | Propose that a package revision should be published. | +| `porchctl rpkg propose-delete` | Propose deletion of a published package revision. | +| `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) | +| `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 @@ -655,6 +656,12 @@ porch-test.network-function3.innerhome5 network-function3 innerh porch-test.network-function3.innerhome6 network-function3 innerhome6 0 false Draft porch-test porch-test.new-package.my-workspace new-package my-workspace 0 false Draft porch-test ``` +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. At this point, a person in _platform administrator_ role, or even an automated process, will review and either approve or reject the deletion. @@ -731,3 +738,27 @@ $ porchctl rpkg upgrade repository.package.1 --workspace=2 --revision=3 # upgrade repository.package.v1 package to revision v3 of its upstream, using copy-merge strategy $ porchctl rpkg upgrade repository.package.1 --workspace=2 --revision=3 --strategy=copy-merge ``` +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 From 656ace3858a4d3d4128d99f971dee52b0366b509 Mon Sep 17 00:00:00 2001 From: lapentafd Date: Thu, 9 Oct 2025 17:50:25 +0100 Subject: [PATCH 2/6] moved sections Signed-off-by: lapentafd --- .../user-guides/deprecation-of-update.md | 21 ++++++++++++- .../porch/user-guides/porchctl-cli-guide.md | 30 ------------------- 2 files changed, 20 insertions(+), 31 deletions(-) diff --git a/content/en/docs/porch/user-guides/deprecation-of-update.md b/content/en/docs/porch/user-guides/deprecation-of-update.md index 3da8bb85..3e04b8dd 100644 --- a/content/en/docs/porch/user-guides/deprecation-of-update.md +++ b/content/en/docs/porch/user-guides/deprecation-of-update.md @@ -14,4 +14,23 @@ For more details, see: https://github.com/nephio-project/nephio/issues/892 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 +For more details, see: https://github.com/nephio-project/porch/pull/252 + +### 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 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 8376ec58..69f99a68 100644 --- a/content/en/docs/porch/user-guides/porchctl-cli-guide.md +++ b/content/en/docs/porch/user-guides/porchctl-cli-guide.md @@ -656,12 +656,6 @@ porch-test.network-function3.innerhome5 network-function3 innerh porch-test.network-function3.innerhome6 network-function3 innerhome6 0 false Draft porch-test porch-test.new-package.my-workspace new-package my-workspace 0 false Draft porch-test ``` -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. At this point, a person in _platform administrator_ role, or even an automated process, will review and either approve or reject the deletion. @@ -738,27 +732,3 @@ $ porchctl rpkg upgrade repository.package.1 --workspace=2 --revision=3 # upgrade repository.package.v1 package to revision v3 of its upstream, using copy-merge strategy $ porchctl rpkg upgrade repository.package.1 --workspace=2 --revision=3 --strategy=copy-merge ``` -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 From 0ccdf8cde8ba7a007e447b47060e8a52c8801761 Mon Sep 17 00:00:00 2001 From: lapentafd Date: Fri, 10 Oct 2025 11:03:02 +0100 Subject: [PATCH 3/6] fix link Signed-off-by: lapentafd --- content/en/docs/porch/user-guides/porchctl-cli-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 69f99a68..c7837eb6 100644 --- a/content/en/docs/porch/user-guides/porchctl-cli-guide.md +++ b/content/en/docs/porch/user-guides/porchctl-cli-guide.md @@ -48,7 +48,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) | +| `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 From f228543450d031a69c48562e3cb02813612cfd52 Mon Sep 17 00:00:00 2001 From: lapentafd Date: Fri, 10 Oct 2025 12:23:10 +0100 Subject: [PATCH 4/6] added root dir to linkinspector config Signed-off-by: lapentafd --- .linkspector.yml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.linkspector.yml b/.linkspector.yml index c75f43b4..ce4e99ce 100644 --- a/.linkspector.yml +++ b/.linkspector.yml @@ -1,6 +1,8 @@ dirs: - . useGitIgnore: true +root: . +checkLocalFiles: true aliveStatusCodes: - 200 @@ -25,9 +27,6 @@ ignorePatterns: - pattern: "https://github\\.com/nephio-project/porch/releases/download/.*/porchctl_.*_linux_amd64\\.tar\\.gz" - pattern: "https://kubernetes\\.io/.*" - - - replacementPatterns: - pattern: ".md#.*$" replacement: ".md" From 2d3a28a63254235fec7bd28845914c5b171a6314 Mon Sep 17 00:00:00 2001 From: lapentafd Date: Fri, 10 Oct 2025 12:29:26 +0100 Subject: [PATCH 5/6] fix typo Signed-off-by: lapentafd --- .linkspector.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.linkspector.yml b/.linkspector.yml index ce4e99ce..18c68bea 100644 --- a/.linkspector.yml +++ b/.linkspector.yml @@ -2,7 +2,7 @@ dirs: - . useGitIgnore: true root: . -checkLocalFiles: true +localFiles: true aliveStatusCodes: - 200 From c7f8238356206286a348dc2b09328f39c75bc4af Mon Sep 17 00:00:00 2001 From: lapentafd Date: Fri, 10 Oct 2025 12:48:10 +0100 Subject: [PATCH 6/6] broken links revert Signed-off-by: lapentafd --- .linkspector.yml | 2 -- .../porch/user-guides/porchctl-cli-guide.md | 30 +++++++++---------- 2 files changed, 15 insertions(+), 17 deletions(-) diff --git a/.linkspector.yml b/.linkspector.yml index 18c68bea..18141fde 100644 --- a/.linkspector.yml +++ b/.linkspector.yml @@ -1,8 +1,6 @@ dirs: - . useGitIgnore: true -root: . -localFiles: true aliveStatusCodes: - 200 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 c7837eb6..be9f6809 100644 --- a/content/en/docs/porch/user-guides/porchctl-cli-guide.md +++ b/content/en/docs/porch/user-guides/porchctl-cli-guide.md @@ -35,21 +35,21 @@ The commands for administering repositories are: The commands for administering package revisions are: -| Command | Description | -| ------------------------------ | -------------------------------------------------------------------------------------------------------------- | -| `porchctl rpkg approve` | Approve a proposal to publish a package revision. | -| `porchctl rpkg clone` | Create a clone of an existing package revision. | -| `porchctl rpkg copy` | Create a new package revision from an existing one. | -| `porchctl rpkg del` | Delete a package revision. | -| `porchctl rpkg get` | List package revisions in registered repositories. | -| `porchctl rpkg init` | Initializes a new package in a repository. | -| `porchctl rpkg propose` | Propose that a package revision should be published. | -| `porchctl rpkg propose-delete` | Propose deletion of a published package revision. | -| `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) | -| `porchctl rpkg upgrade` | Update a downstream package revision to a more recent revision of its upstream package using 3 way merge. | +| Command | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------ | +| `porchctl rpkg approve` | Approve a proposal to publish a package revision. | +| `porchctl rpkg clone` | Create a clone of an existing package revision. | +| `porchctl rpkg copy` | Create a new package revision from an existing one. | +| `porchctl rpkg del` | Delete a package revision. | +| `porchctl rpkg get` | List package revisions in registered repositories. | +| `porchctl rpkg init` | Initializes a new package in a repository. | +| `porchctl rpkg propose` | Propose that a package revision should be published. | +| `porchctl rpkg propose-delete` | Propose deletion of a published package revision. | +| `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 upgrade` | Update a downstream package revision to a more recent revision of its upstream package using 3 way merge. | ## Using the porchctl CLI