Updates to documentation for Porch

content/en/docs/porch/config-as-data.md

@@ -30,8 +30,8 @@ configuration of infrastructure, policy, services, applications, etc.) which:
 
 A system based on CaD should observe the following key principles:
 
-* secrets should be stored separately, in a secret-focused storage system
-  ([example](https://cloud.google.com/secret-manager))
+* secrets should be stored separately, in a secret-focused storage
+system ([example](https://cert-manager.io/))
 * stores a versioned history of configuration changes by change sets to bundles
   of related configuration data
 * relies on uniformity and consistency of the configuration format, including
@@ -64,15 +64,15 @@ Our implementation of the Configuration as Data approach (
 [kpt](https://kpt.dev),
 [Config Sync](https://cloud.google.com/anthos-config-management/docs/config-sync-overview),
 and [Package Orchestration](https://github.com/nephio-project/porch))
-build on the foundation of
+is built on the foundation of
 [Kubernetes Resource Model](https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md)
 (KRM).
 
 {{% alert title="Note" color="primary" %}}
 
 Even though KRM is not a requirement of Config as Data (just like
-Python or Go templates or Jinja are not specifically requirements for
-[IaC](https://en.wikipedia.org/wiki/Infrastructure_as_code)), the choice of
+Python or Go templates or Jinja are not specifically
+requirements for [IaC](https://en.wikipedia.org/wiki/Infrastructure_as_code)), the choice of
 another foundational config representation format would necessitate
 implementing adapters for all types of infrastructure and applications
 configured, including Kubernetes, CRDs, GCP resources and more. Likewise, choice
@@ -106,7 +106,7 @@ and provides the following basic functionality:
 * fork (or clone) an existing package from one package repository (called upstream) to another (called downstream)
 * delete a package from a repository
 * associate a version with the package; guarantee immutability of packages with an assigned version
-* incorporate changes from the new version of an upstream package into a new version of a downstream package
+* incorporate changes from the new version of an upstream package into a new version of a downstream package (3 way merge)
 * revert to a prior version of a package
 
 ## Value
@@ -115,8 +115,6 @@ The Config as Data approach enables some key value which is available in other
 configuration management approaches to a lesser extent or is not available
 at all.
 
-CaD approach enables:
-
 * simplified authoring of configuration using a variety of methods and sources
 * WYSIWYG interaction with configuration using a simple data serialization formation rather than a code-like format
 * layering of interoperable interface surfaces (notably GUI) over declarative configuration mechanisms rather than

content/en/docs/porch/package-orchestration.md

@@ -7,14 +7,14 @@ description:
 
 ## Why
 
-Customers who want to take advantage of the benefits of [Configuration as Data](config-as-data.md) can do so today using
-a [kpt](https://kpt.dev) CLI and kpt function ecosystem, including [functions catalog](https://catalog.kpt.dev/).
+People who want to take advantage of the benefits of [Configuration as Data](config-as-data.md) can do so today using
+a [kpt](https://kpt.dev) CLI and the kpt function ecosystem, including its [functions catalog](https://catalog.kpt.dev/).
 Package authoring is possible using a variety of editors with [YAML](https://yaml.org/) support. That said, a delightful
 UI experience of WYSIWYG package authoring which supports broader package lifecycle, including package authoring with
 *guardrails*, approval workflow, package deployment, and more, is not yet available.
 
-*Package Orchestration* service is part of the implementation of the Configuration as Data approach, and enables
-building the delightful UI experience supporting the configuration lifecycle.
+Porch *Package Orchestration* (Porch) is part of the Nephio implementation of a Configuration as Data approach. It offers an API and
+a CLI that enables building that delightful UI experience for supporting the configuration lifecycle.
 
 ## Core Concepts
 
@@ -51,14 +51,14 @@ considered deployment-ready. ([more details](#deployment))
 The Core implementation of Configuration as Data, *CaD Core*, is a set of components and APIs which collectively enable:
 
 * Registration of repositories (Git, OCI) containing kpt packages and the discovery of packages
-* Porcelain package lifecycle, including authoring, versioning, deletion, creation and mutations of a package draft,
-  process of proposing the package draft, and publishing of the approved package.
+* Management of package lifecycles, including authoring, versioning, deletion, creation and mutations of a package draft,
+  process of proposing the package draft, and publishing of the approved package
 * Package lifecycle operations such as:
 
   * assisted or automated rollout of package upgrade when a new version of the upstream package version becomes
-    available
+    available (3 way merge)
   * rollback of a package to previous version
-* Deployment of packages from deployment repositories and observability of their deployment status.
+* Deployment of packages from deployment repositories and observability of their deployment status
 * Permission model that allows role-based access control
 
 ### High-Level Architecture
@@ -70,7 +70,7 @@ At the high level, the Core CaD functionality comprises:
   * package repository management
   * package discovery, authoring and lifecycle management
 
-* [kpt][] - a Git-native, schema-aware, extensible client-side tool for managing KRM packages
+* [porchctl](using-porch/porchctl-cli-guide) - a Git-native, schema-aware, extensible client-side tool for managing KRM packages
 * a GitOps-based deployment mechanism (for example [Config Sync][]), which distributes and deploys configuration, and
   provides observability of the status of deployed resources
 * a task-specific UI supporting repository management, package discovery, authoring, and lifecycle
@@ -83,7 +83,7 @@ Concepts briefly introduced above are elaborated in more detail in this section.
 
 ### Repositories
 
-[kpt][] and [Config Sync][] currently integrate with [git][] repositories, and there is an existing design to add OCI
+Porch and [Config Sync][] currently integrate with [git][] repositories, and there is an existing design to add OCI
 support to kpt. Initially, the Package Orchestration service will prioritize integration with [git][], and support for
 additional repository types may be added in the future as required.
 
@@ -93,7 +93,7 @@ associated with package to capture:
 * package dependency relationships (upstream - downstream)
 * package lifecycle state (draft, proposed, published)
 * package purpose (base package)
-* (optionally) even customer-defined attributes
+* (optionally) customer-defined attributes
 
 At repository registration, customers must be able to specify details needed to store packages in appropriate locations
 in the repository. For example, registration of a Git repository must accept a branch and a directory.
@@ -117,16 +117,15 @@ Packages are sequentially versioned. The important requirements are:
 * ability to compare any 2 versions of a package to be either "newer than", equal, or "older than" relationship
 * ability to support automatic assignment of versions
 * ability to support [optimistic concurrency][optimistic-concurrency] of package changes via version numbers
-* simple model which easily supports automation
+* a simple model which easily supports automation
 
-We plan to use a simple integer sequence to represent package versions.
+We use a simple integer sequence to represent package versions.
 
 ### Package Relationships
 
 Kpt packages support the concept of ***upstream***. When a package is cloned from another, the new package
-(called ***downstream*** package) maintains an upstream link to the specific version of the package from which it was
-cloned. If a new version of the upstream package becomes available, the upstream link can be used to
-[update](https://kpt.dev/book/03-packages/05-updating-a-package) the downstream package.
+(called the ***downstream*** package) maintains an upstream link to the specific version of the package from which it was
+cloned. If a new version of the upstream package becomes available, the upstream link can be used to update the downstream package.
 
 ### Deployment
 
@@ -191,39 +190,32 @@ The package discovery functionality of Package Orchestration service enables the
   by Config Sync
 * identify new versions of packages in a deployment repository that can be rolled out to a deployment target by Config
   Sync
-* discover functions in registered repositories based on filtering criteria including containing repository,
-  applicability of a function to a specific package or specific resource type(s), function metadata (mutator/validator),
-  idempotency (function is idempotent/not), etc.
 
 ### Package Authoring
 
 The package authoring and lifecycle functionality of the package Orchestration service enables the client to:
 
 * Create a package _draft_ via one of the following means:
 
-  * an empty draft 'from scratch' (equivalent to [kpt pkg init](https://kpt.dev/reference/cli/pkg/init/))
-  * clone of an upstream package (equivalent to [kpt pkg get](https://kpt.dev/reference/cli/pkg/get/)) from either a
+  * an empty draft 'from scratch' (`porchctl rpkg init`)
+  * clone of an upstream package (`porchctl rpkg clone`) from either a
     registered upstream repository or from another accessible, unregistered, repository
-  * edit an existing package (similar to the CLI command(s) [kpt fn source](https://kpt.dev/reference/cli/fn/source/) or
-    [kpt pkg pull](https://github.com/GoogleContainerTools/kpt/issues/2557))
+  * edit an existing package (`porchctl rpkg pull`)
   * roll back / restore a package to any of its previous versions
-    ([kpt pkg pull](https://github.com/GoogleContainerTools/kpt/issues/2557) of a previous version)
+    (`porchctl rpkg pull` of a previous version)
 
-* Apply changes to a package _draft_. In general, mutations include adding/modifying/deleting any part of the package's
+* Push changes to a package _draft_. In general, mutations include adding/modifying/deleting any part of the package's
   contents. Some specific examples include:
 
   * add/change/delete package metadata (i.e. some properties in the `Kptfile`)
   * add/change/delete resources in the package
-  * add function mutators/validators to the package's [pipeline][]
-  * invoke a function imperatively on the package draft to perform a desired mutation
+  * add function mutators/validators to the package's pipeline
   * add/change/delete sub-package
-  * retrieve the contents of the package for arbitrary client-side mutations (equivalent to
-    [kpt fn source](https://kpt.dev/reference/cli/fn/source/))
+  * retrieve the contents of the package for arbitrary client-side mutations (`porchctl rpkg pull`)
   * update/replace the package contents with new contents, for example results of a client-side mutations by a UI
-    (equivalent to [kpt fn sink](https://kpt.dev/reference/cli/fn/sink/))
+    (`porchctl rpkg push`)
 
-* Rebase a package onto another upstream base package
-  ([detail](https://github.com/GoogleContainerTools/kpt/issues/2548)) or onto a newer version of the same package (to
+* Rebase a package onto another upstream base package or onto a newer version of the same package (to
   aid with conflict resolution during the process of publishing a draft package)
 * Get feedback during package authoring, and assistance in recovery from:
 
@@ -246,7 +238,7 @@ The package authoring and lifecycle functionality of the package Orchestration s
 An important goal of the Package Orchestration service is to support building of task-specific UIs. In order to deliver
 low latency user experience acceptable to UI interactions, the innermost authoring loop (depicted below) will require:
 
-* high performance access to the package store (load/save package) w/ caching
+* high performance access to the package store (load/save package) with caching
 * low latency execution of mutations and transformations on the package contents
 * low latency [KRM function][krm functions] evaluation and package rendering (evaluation of package's function
   pipelines)