diff --git a/plans/PhaseA-user-checklist.md b/plans/PhaseA-user-checklist.md new file mode 100644 index 0000000..31f5907 --- /dev/null +++ b/plans/PhaseA-user-checklist.md @@ -0,0 +1,274 @@ +# Fase A — Checklist finale per l'utente + +La Fase A è **code-complete e pushata** sul branch `feature/python-rewrite-phase-a`. +Restano solo le validazioni che richiedono accesso fisico all'host CI con VMware +Workstation, snapshot template attivi e act_runner registrato. + +Questo documento elenca i passi da eseguire in ordine, con checklist e comandi +copiabili. Stop a primo errore: ogni passo è un gate per il successivo. + +> **Tempo stimato totale**: 1–2 ore (escluse build lunghe nel passo 5). + +--- + +## Passo 1 — Aggiornare il venv di produzione sull'host CI + +Il codice nuovo va installato nel venv che act_runner usa +(`F:\CI\python\venv\`). + +- [ ] Aprire PowerShell **come amministratore** sull'host CI. +- [ ] Posizionarsi nella copia git aggiornata del repo (pull del branch + `feature/python-rewrite-phase-a`): + + ```powershell + cd + git fetch origin + git checkout feature/python-rewrite-phase-a + git pull + ``` + +- [ ] Installare il package in editable nel venv di produzione: + + ```powershell + & 'F:\CI\python\venv\Scripts\python.exe' -m pip install -e . + ``` + +- [ ] Smoke check rapido che la CLI risponda: + + ```powershell + & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator --help + ``` + + Atteso: lista degli 11 sub-comandi (`wait-ready`, `vm`, `build`, + `artifacts`, `monitor`, `report`, `job`). + +--- + +## Passo 2 — Riavviare act_runner + +L'act_runner gira come servizio SYSTEM e legge `runner/config.yaml` +all'avvio. La modifica di A4 (`PYTHONIOENCODING=utf-8`) ha effetto solo +dopo restart. + +- [ ] Trovare il servizio: + + ```powershell + Get-Service | Where-Object { $_.Name -like '*act*runner*' } + ``` + +- [ ] Restart (sostituisci `` con quello trovato): + + ```powershell + Restart-Service -Name '' + ``` + +- [ ] Verificare che sia partito: + + ```powershell + Get-Service -Name '' + ``` + + Atteso: `Status = Running`. + +--- + +## Passo 3 — Smoke `wait-ready` su VM Windows reale + +PoC pendente da A1. + +- [ ] Clonare manualmente un template Windows: + + ```powershell + & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' ` + -T ws clone ` + 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' ` + 'F:\CI\BuildVMs\smoke-win\smoke-win.vmx' ` + linked -snapshot=BaseClean -cloneName=smoke-win + ``` + +- [ ] Avviare la VM: + + ```powershell + & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' ` + -T ws start 'F:\CI\BuildVMs\smoke-win\smoke-win.vmx' nogui + ``` + +- [ ] Eseguire `wait-ready`: + + ```powershell + & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator wait-ready ` + --vmx 'F:\CI\BuildVMs\smoke-win\smoke-win.vmx' ` + --guest-os windows --timeout 180 + ``` + + Atteso: exit code `0` entro 3 minuti. + +- [ ] Cleanup VM di smoke: + + ```powershell + & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator vm remove ` + --vmx 'F:\CI\BuildVMs\smoke-win\smoke-win.vmx' --force + ``` + +--- + +## Passo 4 — Smoke `wait-ready` su VM Linux reale + +Stesso schema, template Linux. PoC pendente da A1. + +- [ ] Clonare: + + ```powershell + & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' ` + -T ws clone ` + 'F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx' ` + 'F:\CI\BuildVMs\smoke-linux\smoke-linux.vmx' ` + linked -snapshot=BaseClean-Linux -cloneName=smoke-linux + ``` + +- [ ] Start + wait-ready: + + ```powershell + & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' ` + -T ws start 'F:\CI\BuildVMs\smoke-linux\smoke-linux.vmx' nogui + + & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator wait-ready ` + --vmx 'F:\CI\BuildVMs\smoke-linux\smoke-linux.vmx' ` + --guest-os linux --timeout 180 + ``` + + Atteso: exit code `0`. + +- [ ] Cleanup: + + ```powershell + & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator vm remove ` + --vmx 'F:\CI\BuildVMs\smoke-linux\smoke-linux.vmx' --force + ``` + +--- + +## Passo 5 — Smoke end-to-end pipeline (`job`) + +Valida A3+A4 insieme: clone → wait → build → collect → cleanup. + +- [ ] Lanciare un job sul template Windows con uno script trivial: + + ```powershell + & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator job ` + --template 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' ` + --snapshot BaseClean ` + --name smoke-job-win ` + --build-command 'echo hello > artifact.txt' ` + --artifact-source 'C:\ci\workspace\artifact.txt' ` + --artifact-dest 'F:\CI\Artifacts\smoke-job-win' + ``` + + Atteso: exit code `0`, file `F:\CI\Artifacts\smoke-job-win\artifact.txt` presente, + VM smoke-job-win **non** più esistente in `F:\CI\BuildVMs\` (cleanup garantito). + +- [ ] Ripetere su Linux (cambiare `--template`, `--snapshot`, + `--build-command 'echo hello > artifact.txt'`, + `--artifact-source '/opt/ci/build/artifact.txt'`). + +- [ ] Verificare assenza VM orfane: + + ```powershell + & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator vm cleanup --dry-run + ``` + + Atteso: nessun candidato. + +--- + +## Passo 6 — Workflow Gitea end-to-end + +Validazione di A4 lato runner reale. + +- [ ] Aprire la UI Gitea, repo `local-ci-cd-system`, branch + `feature/python-rewrite-phase-a`. +- [ ] Triggerare manualmente i 3 workflow (Actions → Run workflow): + - [ ] `lint.yml` → atteso PASS + - [ ] `self-test.yml` → atteso PASS + - [ ] `build-nsInnoUnp.yml` matrix Win+Linux → atteso PASS, + artifact pubblicato per entrambe le piattaforme. + +- [ ] Se uno fallisce: scaricare i log dell'esecuzione, aprire issue in + `TODO.md` con sha del workflow run e output errore. + +--- + +## Passo 7 — Burn-in capacità (4 job concorrenti) + +Validazione finale di A5 (definizione di "fatto Fase A"). + +- [ ] Triggerare il workflow `build-nsInnoUnp.yml` 4 volte di seguito + (oppure usare lo script `scripts/Test-CapacityBurnIn.ps1` che ora + delega via shim alla CLI Python `job`): + + ```powershell + .\scripts\Test-CapacityBurnIn.ps1 -Concurrency 4 -Rounds 10 + ``` + +- [ ] Misurare: + - [ ] Tutti i 40 job (4 × 10) PASS + - [ ] Zero VM orfane in `F:\CI\BuildVMs\` a fine burn-in + - [ ] Zero file lock orfani in `F:\CI\BuildVMs\*.lock` + - [ ] Spazio disco libero non scende sotto la soglia di + `Watch-DiskSpace` + +--- + +## Passo 8 — Benchmark wall-clock + +Confronto Python vs PowerShell. Pendenza A4. + +- [ ] Eseguire prima del merge: + + ```powershell + .\scripts\Measure-CIBenchmark.ps1 + ``` + + Annotare il tempo medio per job. + +- [ ] Confrontare con il baseline pre-Python (se disponibile in + `docs/OPTIMIZATION.md` o in un commit precedente). Tolleranza + target: **±10%**. + +- [ ] Se delta > 10%: aprire issue in `TODO.md` con dettagli per + profiling. NON è bloccante per il merge della Fase A. + +--- + +## Passo 9 — Merge della Fase A in `main` + +Solo dopo che i passi 3–7 sono tutti `[x]` PASS. + +- [ ] Aprire PR su Gitea: `feature/python-rewrite-phase-a` → `main`. +- [ ] Verificare diff atteso: ~20 file Python nuovi sotto + `src/ci_orchestrator/`, ~10 shim PS in `scripts/`, doc in + `plans/A*-closeout.md`, AGENTS.md/ARCHITECTURE.md/README.md + aggiornati. +- [ ] Self-review della PR: nessun secret, nessun path hardcodato fuori + da `config.py`, nessun `.venv/` committato. +- [ ] Merge (squash sconsigliato — preserva la storia per-fase). +- [ ] Tag release: `git tag v2.0.0-phaseA` (o convenzione preferita). + +--- + +## Tracciamento globale + +| Passo | Descrizione | Stato | +| ----- | ----------- | ----- | +| 1 | Aggiorna venv di produzione | [ ] | +| 2 | Restart act_runner | [ ] | +| 3 | Smoke `wait-ready` Windows | [ ] | +| 4 | Smoke `wait-ready` Linux | [ ] | +| 5 | Smoke `job` end-to-end (Win + Linux) | [ ] | +| 6 | Workflow Gitea (lint + self-test + build) | [ ] | +| 7 | Burn-in 4 job × 10 round | [ ] | +| 8 | Benchmark wall-clock | [ ] | +| 9 | Merge PR e tag release | [ ] | + +Quando tutti i passi sono `[x]`, la Fase A è **definitivamente chiusa** e +si può aprire la Fase B (porting su host Linux).