157 lines
5.4 KiB
Markdown
157 lines
5.4 KiB
Markdown
<!--
|
|
Mini-manuale per l'uso efficace dell'estensione "Todos" (VS Code)
|
|
Posiziona questo file in `manual/` per consultazione rapida.
|
|
-->
|
|
|
|
# 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):
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```md
|
|
# 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.
|