95 lines
3.3 KiB
Markdown
95 lines
3.3 KiB
Markdown
# 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.
|