Restructured working with PackageRevision guides

content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/_index.md

@@ -2,6 +2,189 @@
 title: "Working with Package Revisions"
 type: docs
 weight: 3
-description: 
+description: A group of guides outlining how to interact with Package Revisions in Porch
 ---
 
+## Prerequisites
+
+- Porch deployed on a Kubernetes cluster [Setup Porch Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}}).
+- **Porchctl** CLI tool installed [Setup Porchctl Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porchctl.md" %}}).
+- A Git repository registered with Porch [Setup Repositories Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md" %}}).
+- **Kubectl** configured to access your cluster.
+
+---
+
+## Understanding Package Revisions
+
+In Porch, you work with **PackageRevisions** - there is no separate "Package" resource. When we say "package" colloquially, we're referring to a PackageRevision. The `rpkg` command stands for "revision package".
+
+PackageRevisions are Kubernetes resources that represent versioned collections of configuration files stored in Git repositories. Each PackageRevision contains:
+
+- **KRM Resources**: Kubernetes Resource Model files (YAML configurations)
+- **Kptfile**: Package metadata and pipeline configuration
+- **Pipeline Functions**: KRM functions that transform package resources
+- **Lifecycle State**: Current state in the package workflow
+
+**PackageRevision Operations:**
+
+- **Creation**: `init`, `clone`, `copy` - Create new PackageRevisions from scratch, existing packages, or new revisions
+- **Inspection**: `get` - List and view PackageRevision information and metadata
+- **Content Management**: `pull`, `push` - Move PackageRevision content between Git repositories and local filesystem
+- **Lifecycle Management**: `propose`, `approve`, `reject` - Control PackageRevision workflow states
+- **Upgrading**: `upgrade` - Create new revision upgrading downstream to more recent upstream package
+- **Deletion**: `propose-delete`, `del` - Propose deletion of published PackageRevisions, then delete them
+
+---
+
+## PackageRevision Lifecycle
+
+PackageRevisions follow a structured lifecycle with three main states:
+
+- **Draft**: Work in progress, fully editable. Revision number is 0.
+- **Proposed**: Ready for review, still editable. Revision number remains 0.
+- **Published**: Approved and immutable. Revision number increments to 1+.
+
+**Lifecycle Transitions:**
+
+1. **Draft → Proposed**: `porchctl rpkg propose` - Signal readiness for review
+2. **Proposed → Published**: `porchctl rpkg approve` - Approve and make immutable
+3. **Proposed → Draft**: `porchctl rpkg reject` - Return for more work
+
+**Additional States:**
+
+- **DeletionProposed**: PackageRevision marked for deletion, pending approval
+
+---
+
+## PackageRevision Naming
+
+Porch generates PackageRevision names automatically using a consistent format:
+
+- **Format**: `{repositoryName}.{packageName}.{workspaceName}`
+- **Example**: `porch-test.my-first-package.v1`
+
+**Name Components:**
+
+- **Repository Name**: Name of the registered Git repository
+- **Package Name**: Logical name for the package (can have multiple revisions)
+- **Workspace Name**: Unique identifier within the package (maps to Git branch/tag)
+
+**Important Notes:**
+
+- Workspace names must be unique within a package
+- Multiple PackageRevisions can share the same package name with different workspaces
+- Published PackageRevisions get tagged in Git using the workspace name
+
+---
+
+## Working with PackageRevision Content
+
+PackageRevisions contain structured configuration files that can be modified through various operations:
+
+**Local Operations:**
+
+1. **Pull**: Download PackageRevision contents to local filesystem
+2. **Modify**: Edit files locally using standard tools
+3. **Push**: Upload changes back to Porch (triggers pipeline rendering)
+
+**Pipeline Processing:**
+
+- KRM functions defined in the Kptfile automatically transform resources
+- Functions run when PackageRevisions are pushed to Porch
+- Common functions: set-namespace, apply-replacements, search-replace
+
+**Content Structure:**
+
+```bash
+package-revision/
+├── Kptfile                   # Package metadata and pipeline
+├── .KptRevisionMetadata      # Porch-managed metadata
+├── package-context.yaml      # Package context information
+├── README.md                 # Package documentation
+└── *.yaml                    # KRM resources
+```
+
+---
+
+## Repository Integration
+
+PackageRevisions are stored in Git repositories registered with Porch:
+
+**Git Branch Mapping:**
+
+- **Draft**: Stored in `draft/{workspace}` branch
+- **Proposed**: Stored in `proposed/{workspace}` branch  
+- **Published**: Tagged as `{workspace}` and stored in main branch
+
+**Repository Types:**
+
+- **Blueprint Repositories**: Contain upstream package templates for cloning
+- **Deployment Repositories**: Store deployment-ready packages (marked with `--deployment` flag)
+
+**Synchronization:**
+
+- Porch automatically syncs with Git repositories
+- Manual sync: `porchctl repo sync <repository-name>`
+- Periodic sync can be configured with cron expressions
+
+---
+
+## Troubleshooting
+
+Common issues when working with PackageRevisions and their solutions:
+
+**PackageRevision stuck in Draft?**
+
+- Check readiness conditions: `porchctl rpkg get <PACKAGE-REVISION> -o yaml | grep -A 5 conditions`
+- Verify all required fields are populated in the Kptfile
+- Check for pipeline function errors in Porch server logs
+
+**Push fails with conflict?**
+
+- Pull the latest version first: `porchctl rpkg pull <PACKAGE-REVISION> ./dir`
+- The PackageRevision may have been modified by someone else
+- Resolve conflicts locally and push again
+
+**Cannot modify Published PackageRevision?**
+
+- Published PackageRevisions are immutable by design
+- Create a new revision using `porchctl rpkg copy`
+- Use the copying workflow to create editable versions
+
+**PackageRevision not found?**
+
+- Verify the exact PackageRevision name: `porchctl rpkg get --namespace default`
+- Check you're using the correct namespace
+- Ensure the repository is registered and synchronized
+
+**Permission denied errors?**
+
+- Check RBAC permissions: `kubectl auth can-i get packagerevisions -n default`
+- Verify service account has proper roles for PackageRevision operations
+- Ensure repository authentication is configured correctly
+
+**Pipeline functions failing?**
+
+- Check function image availability and version
+- Verify function configuration in Kptfile
+- Review function logs in Porch server output during push operations
+
+---
+
+## Key Concepts
+
+Important terms and concepts for working with PackageRevisions:
+
+- **PackageRevision**: The Kubernetes resource managed by Porch (there is no separate "Package" resource)
+- **Workspace**: Unique identifier for a PackageRevision within a package (maps to Git branch/tag)
+- **Lifecycle**: Current state of the PackageRevision (Draft, Proposed, Published, DeletionProposed)
+- **Revision Number**: 0 for Draft/Proposed, 1+ for Published (increments with each publication)
+- **Latest**: Flag indicating the most recent published PackageRevision of a package
+- **Pipeline**: KRM functions defined in Kptfile that transform PackageRevision resources
+- **Upstream/Downstream**: Relationship between source PackageRevisions (upstream) and their clones (downstream)
+- **Repository**: Git repository where PackageRevisions are stored and managed
+- **Namespace Scope**: PackageRevisions exist within a Kubernetes namespace and inherit repository namespace
+- **Rendering**: Process of executing pipeline functions to transform PackageRevision resources
+- **Kptfile**: YAML file containing PackageRevision metadata, pipeline configuration, and dependency information
+
+---

content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md → content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/creating-packages.md

@@ -5,13 +5,6 @@ weight: 3
 description: "A step by step guide to creating a package revision in Porch" 
 ---
 
-## Prerequisites
-
-- Porch deployed on a Kubernetes cluster [Setup Porch Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}}).
-- **Porchctl** CLI tool installed [Setup Porchctl Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}}).
-- A Git repository registered with Porch [Setup Repositories Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/setting-up-repositories.md" %}}).
-- **Kubectl** configured to access your cluster.
-
 ## Tutorial Overview
 
 You will learn how to:
@@ -23,10 +16,6 @@ You will learn how to:
 5. Propose the package revision for review
 6. Approve or reject the package revision
 
-{{% alert title="Understanding Terminology" color="primary" %}}
-In Porch, you work with **PackageRevisions** - there is no separate "Package" resource. When we say "package" colloquially, we're referring to a PackageRevision. The `rpkg` command stands for "revision package".
-{{% /alert %}}
-
 ---
 
 {{% alert title="Note" color="primary" %}}
@@ -313,45 +302,3 @@ If the package revision is rejected, the process begins again from Step 2 until
 ![Diagram](/static/images/porch/guides/lifecycle-workflow.drawio.svg)
 
 ---
-
-## Troubleshooting
-
-**PackageRevision stuck in Draft?**
-
-- Check readiness conditions: `porchctl rpkg get <PACKAGE-REVISION> -o yaml | grep -A 5 conditions`
-
-**Push fails with conflict?**
-
-- Pull the latest version first: `porchctl rpkg pull <PACKAGE-REVISION> ./dir`
-- The PackageRevision may have been modified by someone else
-
-**Cannot modify Published PackageRevision?**
-
-- Published PackageRevisions are immutable
-- Create a new revision using `porchctl rpkg copy` [Copying Package Revisions Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/copying-packages.md" %}}).
-
----
-
-## Understanding PackageRevision Names
-
-Porch generates PackageRevision names automatically:
-
-- Format: `{repoName}.{packageName}.{workspaceName}`
-- Example: `porch-test.my-first-package.v1`
-- The workspace name must be unique within the package
-- Multiple PackageRevisions can share the same package name but have different workspaces
-
----
-
-## Key Concepts
-
-- **PackageRevision**: The Kubernetes resource managed by Porch (there is no separate "Package" resource)
-- **Draft**: Work in progress, fully editable
-- **Proposed**: Ready for review, still editable
-- **Published**: Approved and immutable
-- **Workspace**: Unique identifier for a PackageRevision within a package
-- **Repository**: Git repo where PackageRevisions are stored
-- **Pipeline**: KRM functions that transform PackageRevision resources
-- **Revision Number**: 0 for Draft/Proposed, 1+ for Published (increments with each publication)
-
----

content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md → content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/inspecting-packages.md

@@ -5,16 +5,7 @@ weight: 3
 description: "A guide to getting/listing, reading, querying, and inspecting package revisions in Porch"
 ---
 
-## Prerequisites
 
-- Porch deployed on a Kubernetes cluster [Setup Porch Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}}).
-- **Porchctl** CLI tool installed [Setup Porchctl Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}}).
-- A Git repository registered with Porch [Setup Repositories Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/setting-up-repositories.md" %}}).
-- **Kubectl** configured to access your cluster.
-
-{{% alert title="Understanding Terminology" color="primary" %}}
-In Porch, you work with **PackageRevisions** - there is no separate "Package" resource. When we say "package" colloquially, we're referring to a PackageRevision. The `rpkg` command stands for "revision package".
-{{% /alert %}}
 
 ---
 
@@ -368,36 +359,3 @@ For a complete reference of all available command options and flags, see the [Po
 {{% /alert %}}
 
 ---
-
-## Troubleshooting
-
-**No PackageRevisions shown?**
-
-- Verify repositories are registered and healthy (see [Repository Management Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/setting-up-repositories.md" %}}))
-- Ensure PackageRevisions exist in the Git repository
-
-**Permission denied errors?**
-
-- Check RBAC permissions: `kubectl auth can-i get packagerevisions -n default`
-- Verify service account has proper roles
-
-**PackageRevision not found?**
-
-- Confirm the exact PackageRevision name: `porchctl rpkg get --namespace default`
-- Check you're using the correct namespace
-- Verify the PackageRevision hasn't been deleted
-
----
-
-## Key Concepts
-
-- **PackageRevision**: The Kubernetes resource managed by Porch (there is no separate "Package" resource)
-- **Namespace**: Kubernetes namespace where PackageRevisions are managed
-- **Repository**: Git repository containing PackageRevision sources
-- **Lifecycle**: Current state of the PackageRevision (Draft, Proposed, Published, DeletionProposed)
-- **Workspace**: Unique identifier for a PackageRevision within a package (maps to Git branch/tag)
-- **Latest**: Flag indicating the most recent published PackageRevision of a package
-- **Path nodes**: Directory structure within repository where PackageRevision is located
-- **Revision Number**: 0 for Draft/Proposed, 1+ for Published (increments with each publication)
-
----

content/en/docs/neo-porch/4_tutorials_and_how-tos/upgrading-packages.md → content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/upgrading-packages.md

@@ -9,10 +9,7 @@ The package upgrade feature in Porch is a powerful mechanism for keeping deploye
 
 For detailed command reference, see the [porchctl CLI guide]({{% relref "/docs/neo-porch/7_cli_api/relevant_old_docs/porchctl-cli-guide/#package-upgrade" %}}).
 
-## Prerequisites
 
-*   Porch installed in your Kubernetes cluster, along with its CLI `porchctl`. [Setup Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}})
-*   A Git Repository registered with Porch, in this example it's assumed that the Porch-Repository's name is "porch-test". [Repository Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md" %}})
 
 ## Key Concepts