local-ci-cd-system/plans/PhaseA-user-checklist.md

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):

  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:

  & 'F:\CI\python\venv\Scripts\python.exe' -m pip install -e .
  

• Smoke check rapido che la CLI risponda:

  & '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:

  Get-Service | Where-Object { $_.Name -like '*act*runner*' }
  

• Restart (sostituisci <NomeServizio> con quello trovato):

  Restart-Service -Name '<NomeServizio>'
  

• Verificare che sia partito:

  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:

  & '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:

  & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' `
    -T ws start 'F:\CI\BuildVMs\smoke-win\smoke-win.vmx' nogui
  

• Eseguire wait-ready:

  & '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:

  & '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:

  & '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:

  & '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:

  & '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:

  & '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:

  & '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):

  .\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:

  .\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).