docs(a5): mark A5 as code-complete; add A5-closeout.md
Master checklist + step A5 attivita + 'definizione di fatto' updated; A5-closeout.md added (116 pytest, coverage 80.10% total, gate raised to 80%). Hardware validation (burn-in 4x10 + workflow matrix end-to-end) deferred to user. Shim PS removal deferred to B5 (systemd timers): all 10 shims still referenced by Register-CIScheduledTasks.ps1 / docs / Test-*.ps1.
This commit is contained in:
@@ -0,0 +1,100 @@
|
|||||||
|
# A5 — Closeout
|
||||||
|
|
||||||
|
Fase A5 di `plans/implementation-plan-A-B.md`: polish, regression test
|
||||||
|
per gli errori frequenti `AGENTS.md` #9-#12, documentazione Python
|
||||||
|
allineata, gate coverage alzato a 80%.
|
||||||
|
Branch: `feature/python-rewrite-phase-a`.
|
||||||
|
|
||||||
|
## Stato attuale
|
||||||
|
|
||||||
|
- [x] `tests/python/test_agents_errors.py` aggiunto: 12 test dedicati che
|
||||||
|
coprono regressioni per `AGENTS.md` "Errori frequenti da evitare"
|
||||||
|
#9, #10, #11, #12.
|
||||||
|
- **#9** (snapshot template con VM accesa): `clone_linked` propaga
|
||||||
|
"should not be powered on" come `BackendOperationFailed` (subclass
|
||||||
|
di `BackendError`) con `operation == "clone"` e `output` che
|
||||||
|
contiene il messaggio originale di `vmrun`.
|
||||||
|
- **#10** (`vmrun getGuestIPAddress` lento): `is_running` usa solo
|
||||||
|
`vmrun list`. Tre asserzioni — happy path, VM non listata, errore
|
||||||
|
di `vmrun list` — verificano che `getGuestIPAddress` non venga MAI
|
||||||
|
chiamato come fallback.
|
||||||
|
- **#11** (machine-id duplicato → DHCP collision): la safety net
|
||||||
|
orchestrator-side è che `vm new` non riusi mai un clone-name
|
||||||
|
(timestamp suffix); il test invoca `vm new` due volte con lo stesso
|
||||||
|
`--job-id` e verifica che `clone_linked` riceva due
|
||||||
|
`name`/`destination` distinti. Il fix template-side
|
||||||
|
(`truncate -s 0 /etc/machine-id`) resta documentato in
|
||||||
|
`template/Prepare-LinuxBuild2404.ps1`.
|
||||||
|
- **#12** (`& nativecmd 2>$null` non sopprime stderr in PS 5.1):
|
||||||
|
`SshTransport` usa `paramiko.AutoAddPolicy` di default con
|
||||||
|
`known_hosts=None`, non chiama mai `subprocess.run`/`Popen`
|
||||||
|
(incluso `ssh-keygen`/`ssh.exe`/`scp.exe`), e wrappa errori
|
||||||
|
paramiko (import mancante, `exec_command` exception, SFTP
|
||||||
|
`put`/`get`) come `TransportConnectError` invece di propagare
|
||||||
|
eccezioni nude.
|
||||||
|
- [x] `AGENTS.md` aggiornato: nuova sezione "Python development" subito
|
||||||
|
dopo "PowerShell 5.1 — Vincoli critici", con tabella parametri,
|
||||||
|
convenzioni (type hints, no `Any`/globali/`print`/`shell=True`),
|
||||||
|
mappatura completa PS → Python sub-command, elenco PS che restano
|
||||||
|
e gate coverage 80%.
|
||||||
|
- [x] `docs/ARCHITECTURE.md` esteso con sezione "Python orchestrator
|
||||||
|
(Phase A)": layout package, `VmBackend` Protocol, factory
|
||||||
|
`load_backend(config)`, ricetta Phase C per backend ESXi
|
||||||
|
(`backends/esxi.py` + selettore `[backend]` in `config.toml`),
|
||||||
|
transport selection, gate CI.
|
||||||
|
- [x] `README.md` ampliato: setup venv produzione + dev, esempi CLI per
|
||||||
|
tutti i 10 sub-comandi (`wait-ready`, `vm new/remove/cleanup`,
|
||||||
|
`build run`, `artifacts collect`, `monitor disk/runner`,
|
||||||
|
`report job`, `job`), comandi validazione locale con gate 80%,
|
||||||
|
link a `test_agents_errors.py` e `pyproject.toml`.
|
||||||
|
- [x] Suite completa: ruff clean, mypy --strict clean, **116 pytest
|
||||||
|
PASS**, coverage totale **80.10%** (gate 80% raggiunto).
|
||||||
|
- [ ] Burn-in 4 job concorrenti × 10 round (versione Python di
|
||||||
|
`Test-CapacityBurnIn`) — **richiede VM reali, lasciato a carico
|
||||||
|
utente**.
|
||||||
|
- [ ] Workflow `build-nsInnoUnp.yml` matrix (Win + Linux) end-to-end
|
||||||
|
PASS — eredita pendenza da A4 (richiede runner registrato).
|
||||||
|
|
||||||
|
## Definizione di "fatto" A5
|
||||||
|
|
||||||
|
| Criterio | Stato |
|
||||||
|
| ----------------------------------------------------- | -------------------------------- |
|
||||||
|
| Errori #9–#12 coperti da test pytest | ✅ |
|
||||||
|
| `AGENTS.md` ha sezione "Python development" | ✅ |
|
||||||
|
| `docs/ARCHITECTURE.md` aggiornato (layout + hook C) | ✅ |
|
||||||
|
| `README.md` aggiornato (setup + esempi CLI) | ✅ |
|
||||||
|
| Coverage globale ≥80% (gate alzato in pyproject) | ✅ 80.10% |
|
||||||
|
| Shim PS non referenziati rimossi | ⏭️ nessuno candidato (vedi nota) |
|
||||||
|
| Burn-in 4×10 PASS | ⏳ utente — richiede VM reali |
|
||||||
|
|
||||||
|
**Nota shim PS**: tutti i 10 shim (`Wait-VMReady.ps1`, `New-BuildVM.ps1`,
|
||||||
|
`Remove-BuildVM.ps1`, `Cleanup-OrphanedBuildVMs.ps1`,
|
||||||
|
`Invoke-RemoteBuild.ps1`, `Get-BuildArtifacts.ps1`, `Watch-DiskSpace.ps1`,
|
||||||
|
`Watch-RunnerHealth.ps1`, `Get-CIJobSummary.ps1`, `Invoke-CIJob.ps1`)
|
||||||
|
sono ancora referenziati: `Register-CIScheduledTasks.ps1` registra
|
||||||
|
scheduled task che invocano `Watch-DiskSpace.ps1`,
|
||||||
|
`Watch-RunnerHealth.ps1`, `Cleanup-OrphanedBuildVMs.ps1`; `README.md`
|
||||||
|
documenta `Invoke-CIJob.ps1` per uso manuale; `Test-*.ps1` di smoke
|
||||||
|
chiamano gli shim. Nessuno shim è candidato a rimozione in A5 senza
|
||||||
|
prima migrare anche `Register-CIScheduledTasks.ps1` (Fase B5 lo
|
||||||
|
sostituirà con `*.service` + `*.timer` su systemd).
|
||||||
|
|
||||||
|
## Cosa resta a carico utente
|
||||||
|
|
||||||
|
1. Eseguire un burn-in concorrente (4 job × 10 round) usando il workflow
|
||||||
|
`build-nsInnoUnp.yml` matrix o `scripts/Test-CapacityBurnIn.ps1` (che
|
||||||
|
ora delega via shim alla CLI Python `job`) e verificare:
|
||||||
|
- PASS senza VM orfane (`vm cleanup` non rimuove nulla a fine round).
|
||||||
|
- Wall-clock entro ±20% del baseline pre-Python (`Measure-CIBenchmark.ps1`).
|
||||||
|
2. Validare `build-nsInnoUnp.yml` matrix (Win + Linux) end-to-end PASS
|
||||||
|
sul runner reale — pendenza ereditata da A4.
|
||||||
|
3. Validare `self-test.yml` e `lint.yml` post-switch.
|
||||||
|
|
||||||
|
## Riferimenti commit
|
||||||
|
|
||||||
|
- `test(a5): add pytest regression tests for AGENTS.md errors #9-#12` —
|
||||||
|
`tests/python/test_agents_errors.py`
|
||||||
|
- `docs(a5): document Python orchestrator in AGENTS.md, ARCHITECTURE.md, README.md` —
|
||||||
|
`AGENTS.md`, `docs/ARCHITECTURE.md`, `README.md`
|
||||||
|
- `docs(a5): mark A5 as code-complete; add A5-closeout.md` —
|
||||||
|
`plans/implementation-plan-A-B.md`, `plans/A5-closeout.md`
|
||||||
@@ -68,10 +68,10 @@ A4; cambiano solo path/env vars in Fase B).
|
|||||||
- [x] [A4] Aggiornare `gitea/actions/local-ci-build/action.yml` per invocare la CLI Python direttamente
|
- [x] [A4] Aggiornare `gitea/actions/local-ci-build/action.yml` per invocare la CLI Python direttamente
|
||||||
- [x] [A4] Forzare `PYTHONIOENCODING=utf-8` in `runner/config.yaml`
|
- [x] [A4] Forzare `PYTHONIOENCODING=utf-8` in `runner/config.yaml`
|
||||||
- [ ] [A4] Eseguire workflow `build-nsInnoUnp.yml` (matrix Win+Linux) end-to-end PASS
|
- [ ] [A4] Eseguire workflow `build-nsInnoUnp.yml` (matrix Win+Linux) end-to-end PASS
|
||||||
- [ ] [A5] Convertire errori frequenti `AGENTS.md` #9, #10, #11, #12 in test pytest dedicati
|
- [x] [A5] Convertire errori frequenti `AGENTS.md` #9, #10, #11, #12 in test pytest dedicati
|
||||||
- [ ] [A5] Aggiornare `AGENTS.md` con sezione "Python development" (venv, ruff, mypy, pytest)
|
- [x] [A5] Aggiornare `AGENTS.md` con sezione "Python development" (venv, ruff, mypy, pytest)
|
||||||
- [ ] [A5] Aggiornare `docs/ARCHITECTURE.md` con nuovo layout package
|
- [x] [A5] Aggiornare `docs/ARCHITECTURE.md` con nuovo layout package
|
||||||
- [ ] [A5] Aggiornare `README.md` con setup Python
|
- [x] [A5] Aggiornare `README.md` con setup Python
|
||||||
- [ ] [A5] Eseguire `Test-CapacityBurnIn` (versione Python) 4 job concorrenti PASS
|
- [ ] [A5] Eseguire `Test-CapacityBurnIn` (versione Python) 4 job concorrenti PASS
|
||||||
- [ ] [B1] Installare Linux Mint LTS + aggiornamenti su hardware target
|
- [ ] [B1] Installare Linux Mint LTS + aggiornamenti su hardware target
|
||||||
- [ ] [B1] Installare VMware Workstation Pro Linux (bundle ufficiale Broadcom) e validare `vmrun` su VM di test
|
- [ ] [B1] Installare VMware Workstation Pro Linux (bundle ufficiale Broadcom) e validare `vmrun` su VM di test
|
||||||
@@ -314,15 +314,15 @@ aggiornare documentazione, eseguire burn-in finale.
|
|||||||
|
|
||||||
**Attività**:
|
**Attività**:
|
||||||
|
|
||||||
- [ ] Implementare test pytest dedicati per ognuno degli errori frequenti `AGENTS.md` #9 (snapshot powered-off), #10 (`vmrun list` vs `getGuestIPAddress`), #11 (machine-id reset), #12 (stderr handling — N/A per Python ma documentare)
|
- [x] Implementare test pytest dedicati per ognuno degli errori frequenti `AGENTS.md` #9 (snapshot powered-off), #10 (`vmrun list` vs `getGuestIPAddress`), #11 (machine-id reset → unique clone-name guard), #12 (stderr handling → AutoAddPolicy + no shell-out)
|
||||||
- [ ] Rimuovere shim PS che non hanno call site esterni (verificare con `grep_search` che nessun task / doc li referenzia)
|
- [x] Verificare con `grep_search` che gli shim PS abbiano ancora call site esterni (`Register-CIScheduledTasks.ps1`, doc, `Test-*.ps1`) → nessuno candidato a rimozione in A5; rimozione differita a B5 (systemd timers)
|
||||||
- [ ] Lasciare `Install-CIToolchain-*.ps1`, `Prepare-*.ps1`, `Deploy-*.ps1` in PowerShell (girano dentro guest o per ricostruzione template — vedi §4 di [idea-1](idea-1-python-rewrite.md))
|
- [x] Lasciare `Install-CIToolchain-*.ps1`, `Prepare-*.ps1`, `Deploy-*.ps1` in PowerShell (girano dentro guest o per ricostruzione template — vedi §4 di [idea-1](idea-1-python-rewrite.md))
|
||||||
- [ ] Aggiornare `AGENTS.md`: aggiungere sezione "Python development" (venv path, ruff, mypy strict, pytest, encoding utf-8)
|
- [x] Aggiornare `AGENTS.md`: aggiungere sezione "Python development" (venv path, ruff, mypy strict, pytest, encoding utf-8, mappatura PS → Python)
|
||||||
- [ ] Aggiornare `docs/ARCHITECTURE.md` con nuovo layout `src/ci_orchestrator/`
|
- [x] Aggiornare `docs/ARCHITECTURE.md` con nuovo layout `src/ci_orchestrator/` + Phase C extension point
|
||||||
- [ ] Aggiornare `README.md` con setup Python e quick-start CLI
|
- [x] Aggiornare `README.md` con setup Python e quick-start CLI per tutti i 10 sub-comandi
|
||||||
- [ ] Portare `Test-CapacityBurnIn.ps1` in `commands/burnin.py` (o lasciare in PS se ancora utile come driver esterno)
|
- [ ] Portare `Test-CapacityBurnIn.ps1` in `commands/burnin.py` (o lasciare in PS se ancora utile come driver esterno) — non implementato in A5; lo shim attuale già delega via `job` Python
|
||||||
- [ ] Eseguire burn-in 4 job concorrenti × 10 round PASS sull'host Windows
|
- [ ] Eseguire burn-in 4 job concorrenti × 10 round PASS sull'host Windows — richiede VM reali, a carico utente
|
||||||
- [ ] Aggiornare `docs/RUNBOOK.md` con sezione "Operare da Python CLI"
|
- [ ] Aggiornare `docs/RUNBOOK.md` con sezione "Operare da Python CLI" — deferito a chiusura Fase B (RUNBOOK riscritto end-to-end in B-finale)
|
||||||
|
|
||||||
**Hook futuri Fase C**: documentare in `docs/ARCHITECTURE.md` il
|
**Hook futuri Fase C**: documentare in `docs/ARCHITECTURE.md` il
|
||||||
contratto `VmBackend` come "extension point" e il selettore `[backend]`
|
contratto `VmBackend` come "extension point" e il selettore `[backend]`
|
||||||
@@ -341,11 +341,11 @@ qualche caller esterno non ancora migrato emerge.
|
|||||||
|
|
||||||
**Definizione di fatto step A5**:
|
**Definizione di fatto step A5**:
|
||||||
|
|
||||||
- [ ] Errori #9–#12 coperti da test pytest
|
- [x] Errori #9–#12 coperti da test pytest (`tests/python/test_agents_errors.py`, 12 test)
|
||||||
- [ ] Documentazione aggiornata
|
- [x] Documentazione aggiornata (`AGENTS.md`, `docs/ARCHITECTURE.md`, `README.md`)
|
||||||
- [ ] Shim non referenziati rimossi
|
- [x] Shim non referenziati rimossi → nessuno candidato (tutti referenziati da `Register-CIScheduledTasks.ps1`/doc/`Test-*.ps1`); rimozione differita a B5 con sostituzione systemd
|
||||||
- [ ] Burn-in PASS
|
- [ ] Burn-in PASS — pendenza utente (richiede VM reali, vedi `plans/A5-closeout.md`)
|
||||||
- [ ] **Fase A done**: tutti i criteri di "fatto" §7 soddisfatti per la parte A
|
- [ ] **Fase A done**: code-complete; pending solo validazioni hardware (burn-in + workflow matrix end-to-end)
|
||||||
|
|
||||||
## 2. Fase B — Migrazione host Linux Mint
|
## 2. Fase B — Migrazione host Linux Mint
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user