Upgrade examples on the new docs

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

@@ -5,6 +5,6 @@ weight: 4
 description: Tutorials in Porch
 ---
 
-## Lorem Ipsum
+## Overview
 
-Lorem Ipsum
+> Note: The tutorials in this section assume you have a local development environment running (Porch + Gitea in kind). If you plan to follow the walkthroughs locally, please set up the Local Dev Environment first: [Local Development Environment Setup]({{% relref "/docs/neo-porch/6_configuration_and_deployments/deployments/local-dev-env-deployment.md" %}}).

content/en/docs/neo-porch/4_tutorials_and_how-tos/package-lifecycle.md

@@ -2,9 +2,20 @@
 title: "Package Lifecycle"
 type: docs
 weight: 3
-description: 
+description:
 ---
 
-## Lorem Ipsum
+## Package Lifecycle Workflow
 
-tutorial similar to getting started with first package in getting started section but this time in more detail and with package lifecycle diagram to clearly refference the different stages a package can be in and how it can change
+Packages managed by Porch progress through several states, from creation to final publication. This workflow ensures that packages are reviewed and approved before they are published and consumed.
+
+The typical lifecycle of a package is as follows:
+
+1.  **Draft:** A user initializes a new package or clones an existing one. The package is in a `Draft` state, allowing the user to make changes freely in their local workspace.
+2.  **Proposed:** Once the changes are ready for review, the user pushes the package, which transitions it to the `Proposed` state. In this stage, the package is available for review by other team members.
+3.  **Review and Approval:**
+    *   **Approved:** If the package is approved, it is ready to be published.
+    *   **Rejected:** If changes are required, the package is rejected. The user must pull the package, make the necessary modifications, and re-propose it for another review.
+4.  **Published:** After approval, the package is published. Published packages are considered stable and are available for deployment and consumption by other systems or clusters. They typically become the "latest" version of a package.
+
+![Flowchart](/flowchart.drawio.svg)

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

@@ -2,15 +2,238 @@
 title: "Upgrading Packages"
 type: docs
 weight: 6
-description: 
+description: "A guide to upgrade package revisions using Porch and porchctl"
 ---
 
-## Lorem Ipsum
+# Upgrading Porch Packages
 
-[UPGRADE EXAMPLES] [ALL THE DIFF SCENARIOS] [THIS IS THE MOST COMPLEX PART] [IT NEEDS TO BE VERY SPECIFIC ON WHAT DO/DONT WE SUPPORT] []
+The package upgrade feature in Porch is a powerful mechanism for keeping deployed packages (downstream) up-to-date with their source blueprints (upstream). This guide walks through the entire workflow, from creating packages to performing an upgrade, with a special focus on the different upgrade scenarios and merge strategies.
 
-- [CREATE A GENERIC PACKAGE AND RUN IT THROUGH THE DIFFERENT UPGRADES TO SHOW HOW THEY WORK AND CHANGE]
-- in upgrade scenario we expect that we have NEW BLUEPRINT IS PUBLISHED → DEPLOYMENT PACKAGE CAN BE UPGRADED IF IT WAS BASED ON THAT BLUEPRINT (AKA THE UPSTREAM OF THIS PACKAGE POINTS AT THAT BLUEPRINT). assuming 2 repositories
-- [RESOURCE MERGE] IS A STRUCTURAL 3 WAY MERGE → HAS CONTEXT OF THE STRUCTURE OF THE FILES ->
-- [COPY MERGE] IS A FILE REPLACEMENT STRATEGY → USEFUL WHEN YOU DONT NEED PORCH TO BE AWARE OF THE CONTENT OF THE FILES ESPECIALLY IF THERE IS CONTENT INSIDE THE FILES THAT DO NOT COMPLY WITH KUSTOMIZE.
-  - [OTHER STRATEGIES] …
+## Table of Contents
+
+- [Key Concepts](#key-concepts)
+- [End-to-End Upgrade Example](#end-to-end-upgrade-example)
+- [Understanding Merge Strategies](#understanding-merge-strategies)
+- [Reference](#reference)
+
+## Key Concepts
+
+To understand the upgrade process, it's essential to be familiar with the three states of a package during a merge operation:
+
+*   **Original:** The state of the package when it was first cloned from the blueprint (e.g., `Blueprint v1`). This serves as the common ancestor for the merge.
+*   **Upstream:** The new, updated version of the source blueprint (e.g., `Blueprint v2`). This contains the changes you want to incorporate.
+*   **Local:** The current state of your deployment package, including any customizations you have applied since it was cloned.
+
+The upgrade process combines changes from the **Upstream** blueprint with your **Local** customizations, using the **Original** version as a base to resolve differences.
+
+## End-to-End Upgrade Example
+
+This example demonstrates the complete process of creating, customizing, and upgrading a package.
+
+### Step 1: Create a Base Blueprint Package (v1)
+
+First, we create the initial version of our blueprint. This will be the "upstream" source for our deployment package.
+
+```bash
+# Initialize a new package draft named 'blueprint' in the 'porch-test' repository
+porchctl rpkg init blueprint --namespace=porch-demo --repository=porch-test --workspace=1
+
+# Propose the draft for review
+porchctl rpkg propose porch-test.blueprint.1 --namespace=porch-demo
+
+# Approve and publish the package, making it available as v1
+porchctl rpkg approve porch-test.blueprint.1 --namespace=porch-demo
+```
+
+### Step 2: Create a New Blueprint Version (v2)
+
+Next, we'll create a new version of the blueprint to simulate an update. In this case, we add a new ConfigMap.
+
+```bash
+# Create a new draft (v2) by copying v1
+porchctl rpkg copy porch-test.blueprint.1 --namespace=porch-demo --workspace=2
+
+# Pull the contents of the new draft locally to make changes
+porchctl rpkg pull porch-test.blueprint.2 --namespace=porch-demo ./tmp/blueprint-v2
+
+# Add a new resource file to the package
+kubectl create configmap test-cm --dry-run=client -o yaml > ./tmp/blueprint-v2/new-configmap.yaml
+
+# Push the local changes back to the Porch draft
+porchctl rpkg push porch-test.blueprint.2 --namespace=porch-demo ./tmp/blueprint-v2
+
+# Propose and approve the new version
+porchctl rpkg propose porch-test.blueprint.2 --namespace=porch-demo
+porchctl rpkg approve porch-test.blueprint.2 --namespace=porch-demo
+```
+At this point, we have two published blueprint versions: `v1` (the original) and `v2` (with the new ConfigMap).
+
+### Step 3: Clone Blueprint v1 into a Deployment Package
+
+Now, a user clones the blueprint to create a "downstream" deployment package.
+
+```bash
+# Clone blueprint v1 to create a new deployment package
+porchctl rpkg clone porch-test.blueprint.1 --namespace=porch-demo --repository=porch-test --workspace=1 deployment
+
+# Pull the new deployment package locally to apply customizations
+porchctl rpkg pull porch-test.deployment.1 --namespace=porch-demo ./tmp/deployment-v1
+
+# Apply a local customization (e.g., add an annotation to the Kptfile)
+kpt fn eval --image gcr.io/kpt-fn/set-annotations:v0.1.4 ./tmp/deployment-v1/Kptfile -- kpt.dev/annotation=true
+
+# Push the local changes back to Porch
+porchctl rpkg push porch-test.deployment.1 --namespace=porch-demo ./tmp/deployment-v1
+
+# Propose and approve the deployment package
+porchctl rpkg propose porch-test.deployment.1 --namespace=porch-demo
+porchctl rpkg approve porch-test.deployment.1 --namespace=porch-demo
+```
+
+### Step 4: Discover and Perform the Upgrade
+
+Our deployment package is based on `blueprint.1`, but we know `blueprint.2` is available. We can discover and apply this upgrade.
+
+```bash
+# Discover available upgrades for packages cloned from 'upstream' repositories
+porchctl rpkg upgrade --discover=upstream
+# This will list 'porch-test.deployment.1' as having an available upgrade to revision 2.
+
+# Upgrade the deployment package to revision 2 of its upstream blueprint
+# This creates a new draft package: 'porch-test.deployment.2'
+porchctl rpkg upgrade porch-test.deployment.1 --namespace=porch-demo --revision=2 --workspace=2
+
+# Propose and approve the upgraded package
+porchctl rpkg propose porch-test.deployment.2 --namespace=porch-demo
+porchctl rpkg approve porch-test.deployment.2 --namespace=porch-demo
+```
+
+After approval, `porch-test.deployment.2` is the new, published deployment package. It now contains:
+1.  The `new-configmap.yaml` from the upstream `blueprint.2`.
+2.  The local `kpt.dev/annotation=true` customization applied in Step 3.
+
+## Understanding Merge Strategies
+
+The outcome of an upgrade depends on the changes made in the upstream blueprint and the local deployment package, combined with the chosen merge strategy. You can specify a strategy using the `--strategy` flag (e.g., `porchctl rpkg upgrade ... --strategy=copy-merge`).
+
+### Merge Strategy Comparison
+
+| Scenario                               | `resource-merge` (Default)                               | `copy-merge`                                             | `force-delete-replace`                                   | `fast-forward`                                               |
+| -------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------ |
+| **File added in Upstream**             | File is added to Local.                                  | File is added to Local.                                  | File is added to Local.                                  | Fails (Local must be unchanged).                             |
+| **File modified in Upstream only**     | Changes are applied to Local.                            | Upstream file overwrites Local file.                     | Upstream file overwrites Local file.                     | Fails (Local must be unchanged).                             |
+| **File modified in Local only**        | Local changes are kept.                                  | Local changes are kept.                                  | Local changes are discarded; Upstream version is used.   | Fails (Local must be unchanged).                             |
+| **File modified in both** (no conflict) | Both changes are merged.                                 | Upstream file overwrites Local file.                     | Upstream file overwrites Local file.                     | Fails (Local must be unchanged).                             |
+| **File modified in both** (conflict)   | Merge autoconflic resolution: always choose the new upstream version.                 | Upstream file overwrites Local file.                     | Upstream file overwrites Local file.                     | Fails (Local must be unchanged).                             |
+| **File deleted in Upstream**           | File is deleted from Local.                              | File is deleted from Local.                              | File is deleted from Local.                              | Fails (Local must be unchanged).                             |
+| **Local package is unmodified**        | Upgrade succeeds.                                        | Upgrade succeeds.                                        | Upgrade succeeds.                                        | Upgrade succeeds.                                            |
+
+### Detailed Strategy Explanations
+
+#### `resource-merge` (Default)
+This is a structural 3-way merge designed for Kubernetes resources. It understands the structure of YAML files and attempts to intelligently merge changes from the upstream and local packages.
+
+*   **When to use:** This is the **recommended default strategy** for managing Kubernetes configuration. Use it when you want to preserve local customizations while incorporating upstream updates.
+
+#### `copy-merge`
+A file-level replacement strategy. For any file present in both local and upstream, the upstream version is used, overwriting local changes. Files that only exist locally are kept.
+
+*   **When to use:** When you trust the upstream source more than local changes or when Porch cannot parse the file contents (e.g., non-KRM files).
+
+#### `force-delete-replace`
+The most aggressive strategy. It completely discards the local package's contents and replaces them with the contents of the new upstream package.
+
+*   **When to use:** To completely reset a deployment package to a new blueprint version, abandoning all previous customizations.
+
+#### `fast-forward`
+A fail-fast safety check. The upgrade only succeeds if the local package has **zero modifications** compared to the original blueprint version it was cloned from.
+
+*   **When to use:** To guarantee that you are only upgrading unmodified packages, preventing accidental overwrites of important local customizations.
+
+## Practical examples: upgrade strategies in action
+
+This section contains short, focused examples showing how each merge strategy behaves in realistic scenarios. Each example assumes you have a deployment package `porch-test.deployment.1` cloned from `porch-test.blueprint.1` and that `porch-test.blueprint.2` is available upstream.
+
+### Example A — `resource-merge` (default)
+
+Scenario: Upstream adds a new ConfigMap and local changes added an annotation to Kptfile. `resource-merge` should apply the upstream addition while preserving the local annotation.
+
+Commands (happy path):
+
+```bash
+# discover available upgrades
+porchctl rpkg upgrade --discover=upstream
+
+# perform upgrade using the default strategy
+porchctl rpkg upgrade porch-test.deployment.1 --namespace=porch-demo --revision=2 --workspace=2
+```
+
+Outcome: A new draft `porch-test.deployment.2` is created containing both the new `ConfigMap` and the local annotation.
+
+### Example B — `copy-merge`
+
+Scenario: Upstream changes a file that the local package also modified, but you want the upstream version to win (file-level overwrite).
+
+Commands:
+
+```bash
+porchctl rpkg upgrade porch-test.deployment.1 --namespace=porch-demo --revision=2 --workspace=2 --strategy=copy-merge
+```
+
+Outcome: Files present in both upstream and local are replaced with the upstream copy. Files only present locally are preserved.
+
+### Example C — `force-delete-replace`
+
+Scenario: The blueprint has diverged substantially; you want to reset the deployment package to exactly match upstream v2.
+
+Commands:
+
+```bash
+porchctl rpkg upgrade porch-test.deployment.1 --namespace=porch-demo --revision=2 --workspace=2 --strategy=force-delete-replace
+```
+
+Outcome: The new draft contains only the upstream contents; local customizations are discarded.
+
+### Example D — `fast-forward`
+
+Scenario: You want to ensure upgrades are only applied to unmodified, pristine clones.
+
+Commands:
+
+```bash
+porchctl rpkg upgrade porch-test.deployment.1 --namespace=porch-demo --revision=2 --workspace=2 --strategy=fast-forward
+```
+
+Outcome: The upgrade succeeds only if `porch-test.deployment.1` has no local modifications compared to the original clone. If local changes exist, the command fails and reports the modifications that prevented a fast-forward.
+
+## Reference
+
+### Command Flags
+
+The `porchctl rpkg upgrade` command has several key flags:
+
+*   `--workspace=<name>`: (Mandatory) The name for the new workspace where the upgraded package draft will be created.
+*   `--revision=<number>`: (Optional) The specific revision number of the upstream package to upgrade to. If not specified, Porch will automatically use the latest published revision.
+*   `--strategy=<strategy>`: (Optional) The merge strategy to use. Defaults to `resource-merge`. Options are `resource-merge`, `copy-merge`, `force-delete-replace`, `fast-forward`.
+
+For more details, run `porchctl rpkg upgrade --help`.
+
+### Best Practices
+
+*   **Separate Repositories:** For better organization and access control, keep blueprint packages and deployment packages in separate Git repositories.
+*   **Understand Your Strategy:** Before upgrading, be certain which merge strategy fits your use case to avoid accidentally losing important local customizations. When in doubt, the default `resource-merge` is the safest and most intelligent option.
+
+### Cleanup
+
+To remove the packages created in this guide, you must first propose them for deletion and then perform the final deletion.
+
+```bash
+# Clean up local temporary directory used in these examples
+rm -rf ./tmp
+
+# Propose all packages for deletion
+porchctl rpkg propose-delete porch-test.blueprint.1 porch-test.blueprint.2 porch-test.deployment.1 porch-test.deployment.2 --namespace=porch-demo
+
+# Delete the packages
+porchctl rpkg delete porch-test.blueprint.1 porch-test.blueprint.2 porch-test.deployment.1 porch-test.deployment.2 --namespace=porch-demo
+```

content/en/docs/neo-porch/6_configuration_and_deployments/deployments/local-dev-env-deployment.md

@@ -1,10 +1,91 @@
 ---
-title: "Local/Development Environment Deployment"
+title: "Local Development Environment Setup"
 type: docs
 weight: 3
-description: 
+description: "A guide to setting up a local environment for developing and testing with Porch."
 ---
 
-## Lorem Ipsum
+# Local Development Environment Setup
 
-this section should only explain setting up the dev environment (not how to use it) [example old guide]({{% relref "/docs/neo-porch/6_configuration_and_deployments/relevant_old_docs/environment-setup.md" %}})
+This guide provides instructions for setting up a local development environment using `kind` (Kubernetes in Docker). This setup is ideal for developing, testing, and exploring Porch functionalities.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Local Environment Setup](#local-environment-setup)
+- [Verifying the Setup](#verifying-the-setup)
+
+## Prerequisites
+
+Before you begin, ensure you have the following tools installed on your system:
+
+*   **[Docker](https://docs.docker.com/get-docker/):** For running containers, including the `kind` cluster.
+*   **[kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/):** The Kubernetes command-line tool for interacting with your cluster.
+*   **[kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation):** A tool for running local Kubernetes clusters using Docker container "nodes".
+
+The setup scripts provided in the Porch repository will handle the installation of Porch itself and its CLI, `porchctl`.
+
+## Local Environment Setup
+
+Follow these steps from the root directory of your cloned Porch repository to set up your local environment.
+
+1.  **Bring up the `kind` cluster:**
+
+    This script creates a local Kubernetes cluster with the necessary configuration for Porch.
+
+    ```bash
+    ./scripts/setup-dev-env.sh
+    ```
+
+2.  **Build and load Porch images:**
+
+    **Choose one of the following options** to build the Porch container images and load them into your `kind` cluster.
+
+    *   **CR-CACHE (Default):** Uses a cache backed by a Custom Resource (CR).
+        ```bash
+        make run-in-kind
+        ```
+
+    *   **DB-CACHE:** Uses a PostgreSQL database as the cache backend.
+        ```bash
+        make run-in-kind-db-cache
+        ```
+
+## Verifying the Setup
+
+After the setup scripts complete, verify that all components are running correctly.
+
+1.  **Check Pod Status:**
+
+    Ensure all pods in the `porch-system` namespace are in the `READY` state.
+
+    ```bash
+    kubectl get pods -n porch-system
+    ```
+
+2.  **Verify CRD Availability:**
+
+    Confirm that the `PackageRevision` Custom Resource Definition (CRD) has been successfully registered.
+
+    ```bash
+    kubectl api-resources | grep packagerevisions
+    ```
+
+3.  **Configure `porchctl` (Optional):**
+
+    The `porchctl` binary is built into the `.build/` directory. For convenient access, add it to your system's `PATH`.
+
+    ```bash
+    # You can copy the binary to a directory in your PATH, for example:
+    sudo cp ./.build/porchctl /usr/local/bin/porchctl
+
+    # Alternatively, you can add the build directory to your PATH:
+    export PATH="$(pwd)/.build:$PATH"
+    ```
+
+4.  **Access Gitea UI (Optional):**
+
+    The local environment includes a Gitea instance for Git repository hosting. You can access it at [http://localhost:3000](http://localhost:3000).
+
+    *   **Username:** `nephio`
+    *   **Password:** `secret`