diff --git a/.code-to-docs/style.md b/.code-to-docs/style.md index e69de29b..ca5c58aa 100644 --- a/.code-to-docs/style.md +++ b/.code-to-docs/style.md @@ -0,0 +1,41 @@ +# Code-to-Docs Strict Generation Rules + +Follow these mandatory structural, behavioral, and depth rules when generating or updating documentation based on PR code changes: + +## 1. Zero-Partial Updates Rule (Mandatory Pairings) + +- **Description + Examples Pairing:** Updating a command's description paragraph WITHOUT adding/updating a corresponding CLI code example is considered a FAILED/INCOMPLETE update. +- **If you announce a new capability or flag pattern** (e.g., same-cluster/intra-cluster transfers), you MUST immediately add a matching code block under `## Examples`. + +## 2. Mandatory CLI Examples Standard + +- **Always Provide Concrete Code Blocks:** Every new flag, subcommand behavior, or context variation must include a copy-pasteable bash code block. +- **Use Realistic Flags:** Show exact parameter mappings instead of placeholders. For same-cluster scenarios, explicitly show matching contexts and mapped PVC names: + +```bash +crane transfer-pvc \ + --source-context=mycluster --destination-context=mycluster \ + --pvc-name="mysql-data:mysql-data-new" \ + --pvc-namespace=myapp +``` + +## 3. End-to-End Workflow & Use-Case Integration + +- **Document the Core Business Value / Use-Case:** Do not document commands in isolation. If a code change enables an overarching end-to-end workflow (e.g., StorageClass conversion using `transfer-pvc` + `export` + `transform` + `apply`), document the entire step-by-step pipeline. +- **Mandatory Placement in "Next Steps":** Always integrate multi-command workflows into the `## Next Steps` or `## Workflow` section at the bottom of the document. + +## 4. Capability First, Constraints Second + +- **Feature Announcement:** Always explicitly declare new capabilities and internal handling improvements first before listing restrictions or validation checks. +- **No Minimalist Notes:** Do not settle for adding only a `Note:` or warning box. Expand the main body text and examples accordingly. + +## 5. Pattern Matching & Depth Alignment + +- **Propose Structural Additions:** Do not restrict suggestions to small diffs. Generate complete new sections (`##`, `###`) whenever code changes introduce broad new capabilities or workflows. + +## 6. Preserve Existing Document Structure + +- **Do not rewrite existing paragraphs** unless the code change directly invalidates them. +- **Match the flag syntax style** of the existing file (`--flag=value`, not `--flag value`). +- **Match heading levels and formatting** (bullet style, code block language tags) exactly as they appear in the current file. +- **Minimal footprint:** touch only what the PR changes require. Do not refactor, reword, or reformat content that is unrelated to the code change. diff --git a/docs/.doc-index/_root.index.md b/docs/.doc-index/_root.index.md new file mode 100644 index 00000000..8d094330 --- /dev/null +++ b/docs/.doc-index/_root.index.md @@ -0,0 +1,36 @@ +# _ROOT Documentation Index + +## Overview +This documentation area defines the **Crane Migration Tool's** transformation pipeline, resource compatibility standards, and validation procedures. It serves as the definitive guide for engineers performing cluster migrations using the `crane` CLI, covering everything from the multi-stage Kustomize architecture to pre-deployment manifest validation and environment-specific troubleshooting. + +## Files Summary +* **kustomize-multistage.md**: Describes the sequential multi-stage Kustomize pipeline, including directory structure, plugin prioritization, stage chaining, and the "dirty check" mechanism. +* **CRANE_COMPATIBILITY_MATRIX.md**: Outlines the scope of migration support for various Kubernetes resources, distinguishing between fully supported namespace-scoped objects and conditionally supported cluster-scoped infrastructure. +* **pre-apply-validation-guide.md**: Provides a comprehensive checklist and script for validating rendered manifests against a target cluster to prevent partial deployments or permission errors. +* **transform.md**: Details the internal structure of the `transform/` directory, including how to manage manual edits, pass-through stages, and the workflow for integrating custom plugins. +* **stateless-migration-quickstart.md**: Offers an end-to-end tutorial for the standard Crane migration workflow, encompassing export, transform, apply, and validate phases. + +## Code Changes That Would Require Documentation Updates +* **Pipeline Schema Changes**: Any modification to the `transform/` directory layout, `kustomization.yaml` requirements, or the `[priority]_[plugin-name]` naming convention. +* **CLI Flag Additions/Removals**: Changes to `crane transform`, `crane apply`, or `crane export` flags (e.g., modifying how `--force` or `--stage` works). +* **Plugin System Updates**: Changes to how plugins are loaded, how priorities are calculated, or how they interact with the transformation chain. +* **Compatibility Logic**: Updates to which resources are automatically white-listed or excluded during the `export` or `transform` phases. +* **Validation/Dry-Run Logic**: Modifications to the `kubectl` checks, API compatibility validation, or the logic within the `validate` command. +* **New Intermediate Stages**: Changes to the automated staging behavior (e.g., adding automatic pre- or post-processing stages). + +## Key Technical Concepts +* **Multi-Stage Pipeline**: Sequential transformation using `[priority]_[plugin-name]` directories. +* **Kustomize Integration**: Using `kustomization.yaml` and `patches/` to modify exported resources. +* **Dirty Check**: Protection mechanism that prevents overwriting user-modified stages without `--force`. +* **Resource Whiteout**: The process of excluding unwanted cluster-specific metadata or resources. +* **Server-Side Dry-Run**: Using `kubectl apply --dry-run=server` for real-time validation against the target cluster API. +* **Pass-Through Stages**: Non-plugin stages used for manual YAML editing. +* **RBAC Context**: Requirements for `get`/`create` permissions on cluster-scoped resources. +* **Namespace-Scoped vs. Cluster-Scoped**: Classification logic for determining migration eligibility. + +## Related Components +* **`crane-lib`**: The underlying library for plugins and transformation utilities. +* **`kubectl` / `oc`**: The primary external tools used for validation and application. +* **Kustomize**: The engine used to render final manifests. +* **Export/Import Subsystems**: The core components responsible for resource discovery and serialization. +* **Validation Module**: The subsystem responsible for live cluster compatibility checks. \ No newline at end of file diff --git a/docs/.doc-index/manifest.json b/docs/.doc-index/manifest.json new file mode 100644 index 00000000..20bb5cc5 --- /dev/null +++ b/docs/.doc-index/manifest.json @@ -0,0 +1,17 @@ +{ + "version": "1.0", + "created": "2026-07-30T16:19:24.136600", + "folders": { + "_root": { + "built": "2026-07-30T16:19:27.932011", + "doc_hashes": { + "kustomize-multistage.md": "28ae2a4049b2c8d7b3c09ceb09a5a3951f46620ec7d51ec8141fd19bbfe35d7d", + "CRANE_COMPATIBILITY_MATRIX.md": "3344f95d520f5a237f5d196b8d2d41d8314e8b9a362ce9c49d61ee36f5e7bd2b", + "pre-apply-validation-guide.md": "4d9ece1a2c840cb94051b519b3cbc09efc0e0b0d5937049f0800a1000737573b", + "transform.md": "0a1bb30a5350c6685988951e61510734e138b24192cd37a7ed1be32ce94f661c", + "stateless-migration-quickstart.md": "3e71d1b07780a0c763ed41c9e5f54535c6d9dd265fbb3a5ab7cf2642d231339e" + } + } + }, + "updated": "2026-07-30T16:19:27.932937" +} \ No newline at end of file