From f2b888386c8cce6e6e6372c1ece070935012520d Mon Sep 17 00:00:00 2001 From: rcourtman Date: Thu, 13 Nov 2025 22:36:01 +0000 Subject: [PATCH] Remove installer v2 rollout doc --- CONTRIBUTING.md | 4 +- docs/README.md | 1 - docs/installer-v2-rollout.md | 95 ------------------------------------ 3 files changed, 1 insertion(+), 99 deletions(-) delete mode 100644 docs/installer-v2-rollout.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0a31a93..c12427c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -85,8 +85,7 @@ UI-heavy features. - Tests: `scripts/tests/run.sh` plus integration suites under `scripts/tests/integration/` -Document rollout plans and kill switches in `docs/installer-v2-rollout.md` and -`MIGRATION_SCAFFOLDING.md`. +Document rollout plans and kill switches in `MIGRATION_SCAFFOLDING.md` so future contributors know how to disable risky changes. --- @@ -136,4 +135,3 @@ before submitting large doc updates. Reviewers will focus on correctness, security, and upgrade paths, so call out anything unusual up front. Thanks again for contributing! - diff --git a/docs/README.md b/docs/README.md index 5e6c9c2..b36009d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -49,7 +49,6 @@ section groups related guides so you can jump straight to the material you need. - [CONTRIBUTING.md](../CONTRIBUTING.md) – Repository-wide contribution guide. - [script-library-guide.md](script-library-guide.md) – Working with shared Bash modules. -- [installer-v2-rollout.md](installer-v2-rollout.md) – Process for shipping major installer updates. - [development/MOCK_MODE.md](development/MOCK_MODE.md) – Using mock data while developing. - [MIGRATION_SCAFFOLDING.md](../MIGRATION_SCAFFOLDING.md) – Tracking temporary migration code. diff --git a/docs/installer-v2-rollout.md b/docs/installer-v2-rollout.md deleted file mode 100644 index 649d70b..0000000 --- a/docs/installer-v2-rollout.md +++ /dev/null @@ -1,95 +0,0 @@ -# Installer v2 Rollout Playbook - -This playbook captures the agreed rollout process for major installer updates -(`install.sh`, host/agent installers, and supporting bundles). Use it when -cutting a new installer generation or deprecating legacy flows. - ---- - -## 1. Define Objectives - -- Document the functional changes (new flags, platforms, security updates). -- Outline compatibility expectations (supported OS versions, container - runtimes, Proxmox releases). -- Decide which behaviours remain behind feature flags or environment toggles. - -Create a tracking issue with: -- Summary of the change -- Owners for implementation, docs, and QA -- Planned release milestone - ---- - -## 2. Build in Parallel - -While the existing installer continues shipping: - -1. Implement changes under `scripts/install-*-v2.sh` (keep the original script - untouched). -2. Gate sensitive logic behind `PULSE_INSTALLER_V2` or similar flags so you can - exercise new code paths without breaking production users. -3. Add migration scaffolding to handle legacy configs—record details in - `MIGRATION_SCAFFOLDING.md`. - ---- - -## 3. Testing Matrix - -Cover these scenarios before merging: - -| Scenario | Notes | -|----------|-------| -| Fresh install on Debian/Ubuntu | Include root + non-root invocation, interactive + `--force`. | -| Proxmox LXC creation | Validate resource sizing, storage defaults, and rollback on failure. | -| Docker / Compose flow | Ensure bind mounts, auto-hash, and setup wizard paths remain intact. | -| Upgrade in place | Re-run installer on an existing deployment; preserve data and services. | -| Air-gapped mode | Exercise `--offline` or pre-downloaded assets if supported. | -| Uninstall / cleanup | Confirm services and temp files are removed where promised. | - -Automate what you can with `scripts/tests/integration/`. Record any manual -checks in the tracking issue. - ---- - -## 4. Documentation Updates - -- Update end-user docs (`docs/INSTALL.md`, Docker/Kubernetes guides) with new - flags and workflows. -- Refresh quick-start snippets in `README.md`. -- Note behavioural changes in `docs/RELEASE_NOTES.md` under the relevant - version once the rollout ships. -- Keep `docs/script-library-guide.md` aligned with any new patterns so future tweaks stay consistent with the rollout plan. - ---- - -## 5. Staged Rollout - -1. Merge v2 into `main` behind a feature flag or version guard. -2. Ask beta testers to opt-in via `--use-installer-v2` (or similar). -3. Monitor GitHub issues / Discord for feedback. -4. Iterate quickly on regressions—keep the old installer intact until v2 is - stable. - -When metrics show low regression risk, switch the default path to v2 but keep -the v1 flag available for at least one stable release. - ---- - -## 6. Sunset Legacy Paths - -- Announce deprecation in release notes at least one version before removal. -- Remove the legacy flag after the deprecation window. -- Delete scaffolding and update `MIGRATION_SCAFFOLDING.md` to reflect the - cleanup. - ---- - -## 7. Post-Rollout Checklist - -- Audit bundled artifacts (`dist/*.sh`) for unexpected diffs. -- Regenerate checksums and publish updated hashes if distributing binaries. -- Close the tracking issue with a summary of lessons learned and follow-up - tasks (e.g., telemetry improvements). - -Keeping this playbook up to date ensures future installer iterations follow the -same predictable rollout process and reduces duplicate tribal knowledge.