docs: add Fase A user checklist for hardware validation
This commit is contained in:
@@ -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 <path-locale-repo>
|
||||||
|
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 `<NomeServizio>` con quello trovato):
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
Restart-Service -Name '<NomeServizio>'
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] Verificare che sia partito:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
Get-Service -Name '<NomeServizio>'
|
||||||
|
```
|
||||||
|
|
||||||
|
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).
|
||||||
Reference in New Issue
Block a user