S1005403_RisCC/doc/todos_extension_manual.md

Guida rapida: Estensione "Todos" in Visual Studio Code

Questo mini-manuale spiega come installare, configurare e sfruttare al massimo l'estensione "Todos" (o estensioni simili che indicizzano checkbox/annotazioni nei file) per gestire il file todo.md del progetto. È pensato per essere pratico e immediatamente applicabile.

---

1) Obiettivo

• Centralizzare task e micro-attività nel repository in un file leggibile (todo.md).
• Usare l'estensione per: filtrare, navigare, assegnare e trasformare rapidamente i task.

2) Installazione e attivazione

1. Apri VS Code.
2. Marketplace → cerca Todos (o todo tree, todo+ ecc.).
3. Installa l'estensione che preferisci (es. "Todos" by Alexandru Duma o simile).
4. Dopo l'installazione, apri la Command Palette (Ctrl+Shift+P) e cerca comandi come:
   • Todos: Show o Todos: Toggle per visualizzare la vista globale dei todo.
5. (Opzionale) Aggiungi impostazioni di workspace per includere/escludere percorsi.

Esempio .vscode/settings.json (opzionale):

{
  "todos.include": ["**/todo.md", "**/*.md"],
  "todos.exclude": ["**/node_modules/**", "**/.venv/**"]
}

---

3) Convenzioni consigliate per todo.md

Usare una convenzione coerente rende la ricerca e il filtering più potenti.

• Ogni task su una riga, checkbox Markdown:
  • - [ ] per aperto, - [x] per completato.
• Aggiungere tag e metadati inline:
  • #feature, #bug, #test, #docs — permette filtri tematici.
  • @owner — persona responsabile.
  • prio:high|medium|low — priorità.
  • est:30m|1h|2h — stima.
  • target_id:<id> — utile per tracciare target nel CSV o riferimenti interni.

Esempio di riga completa:

- [ ] Implementare MathLab CSV export #feature @marco prio:high est:3h target_id:all

---

4) Struttura consigliata del file

Usa sezioni per organizzare lo stato del lavoro:

• # TODOs (header principale con note sulle convenzioni)
• ## Inbox — cattura rapida di idee e richieste
• ## Backlog — attività pianificate ma non prioritarie
• ## Sprint — attività previste nel prossimo ciclo
• ## Doing — attività in corso (opzionale)
• ## Done — attività completate

Esempio di template:

# TODOs - convenzioni: #tag @owner prio:<high|med|low> est:<time>

## Inbox
- [ ] Aggiungere MathLab export dialog #feature @marco prio:high est:2h
- [ ] Creare unit tests per add_mathlab_state #test @marco prio:medium est:1h

## Backlog
- [ ] Refactor logger CSV #chore @team prio:low est:4h

## Sprint W01
- [ ] Fix heading calculation #bug @luca prio:high est:30m

## Done
- [x] Aggiornare SimulationEngine per chiamare archive.add_mathlab_state #feature @marco

---

5) Workflow raccomandato

1. Capture — aggiungi immediatamente la riga in todo.md quando nasce un task.
2. Triage (giornaliero) — assegna tag/owner/estimate alle voci nuove (#bug/prio).
3. Plan (settimanale) — sposta le voci in ## Sprint se da fare nella settimana.
4. Work — mentre lavori, aggiorna la riga (- [ ] → - [x]) e nel commit/PR metti riferimento alla riga.
5. Archive — sposta voci completate nella sezione ## Done o elimina dopo verifica.

Consiglio: nel PR/commit message includi una riga che faccia riferimento al task, es.: Fixes TODO: Implementare MathLab CSV export.

---

6) Come usare l'estensione (operazioni tipiche)

• Aprire la vista Todos: Command Palette → Todos: Show.
• Filtrare per tag: usa la ricerca integrata dell'estensione o il filtro #bug.
• Creare task dalla UI: molte estensioni permettono di creare righe direttamente dalla vista (prova Todos: Create Task).
• Cliccare per navigare alla riga nel file quando la vista elenca i task.

---

7) Best practices e consigli avanzati

• Mantieni le voci piccole e atomiche.
• Non usare todo.md come backlog di alto livello (usa invece issue/board), ma per micro-task.
• Standardizza i tag del team e scrivili in testa al file in # conventions.
• Se lavori in team, aggiungi una sezione Contributors con le convenzioni condivise.
• Evita duplicati: prima di aggiungere, cerca parole chiave nel file.

Automazioni possibili:

• Script che convertono todo.md in issue GitHub (CI/CD)
• Hook che rimuovono voci - [ ] obsolete quando la PR viene unita (con commento di audit)

---

8) Esempi pratici (rapidi)

• Aggiungere un bug:
  • - [ ] Correggere crash all'avvio #bug @luca prio:high est:1h
• Assegnare un task in triage:
  • trova #bug nella vista Todos, apri e aggiungi @owner prio:high est:30m.
• Segnare completato:
  • modifica la riga in - [x] o usa la UI dell'estensione.

---

9) Esercizi rapidi (per padroneggiare)

1. Apri todo.md e aggiungi 3 task di esempio con tag/owner/estimate.
2. Filtra la vista dell'estensione per @tuo_nome e verifica che compaiano solo i task assegnati a te.
3. Crea una PR che risolve un task e, nel messaggio, inserisci Closes TODO: <descrizione>.

---

10) Risorse utili e next steps

• Se vuoi, posso:
  • popolare todo.md con il template che preferisci;
  • aggiungere uno script che esporta todo.md in CSV o in issue GitHub;
  • aggiungere esempi di automazione CI.

Salva questa guida come riferimento in manual/todos_extension_manual.md.

Buon lavoro — se vuoi che inserisca il template direttamente in todo.md, lo faccio ora.