Porch Documentation Restructure

The Kubernetes documentation follows a table of contents detailed in the below section. taking this template and adapting it to the porch code base/documentation we get the following.

1. The different sections required to be covered following the Kubernetes documentation.
2. The currently available documentation relating to this section available now on https://docs.nephio.org/docs/porch/.
3. The gaps/missing sections not found in the current documentation but required in the rework.

Sections marked as [Section in Green] means they have been reviewed and marked as necessary to be included in the new documentation.

Sections marked as [Section in Red] means they have not been reviewed but could still be placed in the docs in the given location once they are. TLDR its a topic of interest to be looked at just not signed off on yet as as a mandatory addition.

Table of Contents

1. Overview
2. Concepts
3. Getting Started
4. Tutorials & How‑tos
5. Architecture & Components
6. Configuration & Deployment
7. CLI / API / Reference
8. Best Practices & Patterns
9. Troubleshooting & FAQ
10. Security & Compliance
11. Glossary
12. Contributing
13. Release Notes / Changelog

1. Overview

Section Must Contain:

• What is Porch   • Short description (“Porch = package orchestration, opinionated package management …”) (Porch already has this under Overview). ( https://docs.nephio.org/docs/porch/)
• Goals & scope (what Porch intends to do, what it does not do)
• Audiences: which users should care (operators, GitOps engineers, developers, integrators, etc.)
• Prerequisites / compatibility (Kubernetes versions, environments, permissions, dependencies)

Currently Available Resources:

• Porch documentation ( https://docs.nephio.org/docs/porch/)
• Overview — what Porch is. ( https://docs.nephio.org/docs/porch/) exists but requires refresh
• Porch in the Nephio architecture, history and outlook (exists but we should do away with it)

Gaps / additions Required:

• Statement of goals & scope (what Porch intends to do / NOT do).
• Target audiences (operators, developers, integrators).
• Supported environments / prerequisites summary.

2. Concepts

Section Must Contain:

• Key terminology (package, variant, mutation pipeline, function runner, etc.)
• Core models/entities: what Porch works with (packages, modules, variants, pipelines).
• High‑level flow / lifecycle: how a package moves through Porch (creation → mutation → deployment or consumption)
• Relationships to other Nephio components / external systems (Git repos, registries, etc.)

Currently Available Resources:

• Porch Concepts
• Configuration as Data
• Package Mutation Pipeline Order
• Function Runner Pod Templating
• Package Variant Controller

Gaps / additions Required:

• Central glossary of key terms
• Visual lifecycle diagram of a package
• Mapping of Porch functions vs Nephio components

3. Getting Started

Section Must Contain:

• Install Porch: requirements, supported platforms/environments, step‑by‑step install. Porch already has Installing Porch.
• Environment preparation: what users need locally, or on a cluster. (Porch has Preparing the Environment.)
• First example / quick start: minimal working example (e.g. a package, mutate, deploy)
• Using the Porch CLI / basic commands. Porch has Using the Porch CLI tool.

Currently Available Resources:

• Installing Porch needs quick version e.g. script containing (./scripts/setup-dev-env.sh + make run-in-kind)
• Preparing the Environment
• Using the Porch CLI tool

Gaps / additions Required:

• End-to-end quickstart walkthrough
• Output examples (logs/screenshots)
• Supported platforms/environment matrix

4. Tutorials & How‑to’s

Section Must Contain:

• Common tasks with step‑by‑step instructions:
  • Authenticating with remote Git repositories.
  • Using private registries.
  • Running Porch in different environments (cloud, on‑prem, VMs). E.g. Running Porch on GKE.
• Advanced how‑tos: customizing the mutation pipeline, variant selection, function runner templating, etc.

Currently Available Resources:

• Authenticating with remote Git
• Using authenticated private registries
• Running Porch on GKE
• Mutation pipeline & function runner content (under Concepts)

Gaps / additions Required:

• Complete end-to-end sample with full mutation + deployment
• Real-world examples (multi-repo setups)
• CI/CD testing integration

5. Architecture & Components

Section Must Contain:

• Overall architecture diagram
• Main components/modules of Porch (controllers, function runner, variant controller, etc.)
• Data flow and interaction: how packages move through system, lifecycle events, error paths, etc.
• Dependencies: e.g. what external services Porch relies on (Git, registry, Kubernetes APIs)

Currently Available Resources:

• Porch in the Nephio Architecture
• Individual component pages: Function Runner, Variant Controller, etc.

Gaps / additions Required:

• Single consolidated diagram of Porch system
• Component interaction maps
• Package lifecycle description and flow diagram

6. Configuration & Deployment

Section Must Contain:

• Configuration options (config as data, configuration schema) — key settings, environment variables, flags. Porch has Configuration as Data.
• Deployment modes: how Porch can be deployed (cluster, single VM, etc.)
• Versioning and upgrades
• Authentication, authorization configuration (connecting to Git, registries)

Currently Available Resources:

• Configuration as Data
• Git & Registry Auth (under How-Tos)
• GKE Deployment Guide

Gaps / additions Required:

• Config file schema and field definitions
• Supported deployment topologies
• Upgrade instructions / versioning policy

7. CLI / API / Reference

Section Must Contain:

• CLI tool reference: all commands, flags, examples
• APIs / CRDs / Resources: full spec for Porch‑specific Kubernetes resources, with fields, validation, defaulting
• Schema definitions or API versioning
• Configuration schema reference, file formats etc.

Currently Available Resources:

• CLI usage guide (basic) https://docs.nephio.org/docs/porch/user-guides/porchctl-cli-guide/

Gaps / additions Required:

• Full CLI command reference (flags, subcommands)
• CRD reference (e.g., PackageVariant, Repository)
• YAML schema definitions and validation docs

8. Best Practices & Patterns

Section Must Contain:

• Recommendations for structuring packages, versions & variants
• How to design reusable templates/functions
• Performance / scaling tips (e.g. for large numbers of packages or functions)
• Operational guidance: monitoring, logging, health checks

Currently Available Resources:

• Not directly addressed

Gaps / additions Required:

• Package/variant organization patterns
• Best practices for reusable mutations/functions
• Monitoring/logging guides

9. Troubleshooting & FAQ

Section Must Contain:

• Common problems & their solutions
• Error messages & diagnostic steps
• Debugging tips / tools
• FAQ: questions new users often ask

Currently Available Resources:

• None found

Gaps / additions Required:

• FAQ page
• Error resolution page
• CLI diagnostic/debugging guide

10. Security & Compliance

Section Must Contain:

• Authentication & authorization: how Porch ensures secure access
• Secrets / credentials handling (for Git, registries, etc.)
• Security considerations for function runner / templates / untrusted code
• TLS, encryption in transit / at rest if applicable

Currently Available Resources:

• Git & Registry authentication (under How-Tos)

Gaps / additions Required:

• Security model for untrusted functions
• Secrets handling / rotation model
• RBAC requirements and guidance

11. Glossary

Section Must Contain:

• Define domain‑specific or technical terms used throughout the docs (variant, package orchestration, mutation, etc.)

Currently Available Resources:

• An old and likely in need of reconstruction glossary page was found here https://docs.nephio.org/docs/glossary-abbreviations/

Gaps / additions Required:

• Term definitions + cross-links

12. Contributing

Section Must Contain:

• How to contribute (code, documentation)
• Developer setup (how to build and run Porch locally) — Porch has Setting up a local environment.
• Process for submitting changes, code review, governance

Currently Available Resources:

• Developer setup guide

Gaps / additions Required:

• CONTRIBUTING.md page with PR process
• Code style conventions
• Maintainer guide / governance model

13. Release Notes / Changelog

Section Must Contain:

• What’s new in each release
• Breaking changes, deprecations
• Migration guides if necessary

Currently Available Resources:

• None found in public docs

Gaps / additions Required:

• Changelog per version
• Migration instructions
• Release tagging structure