Una segnalazione di bug è un insieme di istruzioni per riprodurre qualcosa che hai già visto. Ha funzionato quando chi non era presente riesce a far succedere la stessa cosa al primo tentativo, e ha fallito quando quella persona deve tornare da te a fare una domanda.
Tutto quello che segue è scritto a partire da questa sola prova. Sette cose a cui una segnalazione deve rispondere, un modello che le chiede nell’ordine giusto e una segnalazione vera riscritta a partire dalla versione che sarebbe stata rimandata indietro.
Se cerchi il ragionamento sul perché le segnalazioni falliscono più che i requisiti in sé, l’articolo di accompagnamento sui dieci errori comuni nelle segnalazioni di bug tratta le abitudini che costano più tempo.
A che cosa deve rispondere una segnalazione
Il titolo
Un titolo viene letto molte volte e aperto una sola. Compare nella ricerca, nel daily, nelle note di rilascio e nella lista che qualcuno scorre mentre sceglie cosa prendere in carico. Scrivilo come ciò che non ha funzionato, più dove o quando, più il dettaglio che separa il tuo caso da quello di tutti gli altri, a cui funziona.
- Debole
- Login rotto
- Meglio
- Il pulsante di accesso non risponde dopo l'inserimento delle credenziali su Firefox 121, Windows 11
I passaggi
Numerali e parti da uno stato che chiunque possa raggiungere. Non “vai nel mio account”, ma l’accesso, i dati e ogni azione nell’ordine in cui l’hai compiuta. Chiudi con quello che hai visto, così chi legge sa quando è arrivato.
1. Aprire https://example.com/login
2. Inserire l'email test@example.com e la password TestPass123!
3. Fare clic su Accedi
4. Osservazione: il pulsante mostra un breve stato di caricamento e torna normale. Nessuna navigazione.
Consegnali a qualcuno che non ha visto il bug. Se ti chiede qualcosa, la risposta è il tuo passaggio mancante.
Comportamento atteso e comportamento reale
Scrivili entrambi. “Il login non funziona” dà per scontato che chi legge sappia com’è quando funziona, e a volte quello che stai segnalando si rivela una regola che non conoscevi.
- Atteso
- L'utente viene reindirizzato a /dashboard dopo un accesso riuscito
- Reale
- Il pulsante carica per circa un secondo, torna al suo stato normale e la pagina non cambia
L’ambiente
Un difetto che si presenta ovunque e un difetto che si presenta in un solo browser hanno cause diverse, e nessuno può dire quale sia il tuo finché qualcuno non controlla. Annota il browser e la sua versione, il sistema operativo, il dispositivo e la dimensione della finestra se è coinvolto il layout.
Ultimo Chrome non è una versione. Significa una cosa il giorno in cui la scrivi e un’altra il
giorno in cui viene letta.
Le prove visive
Uno screenshot risolve subito un problema di layout o di testo. Una registrazione è meglio per tutto ciò che riguarda tempi, animazioni o una sequenza. Cattura l’intera finestra invece dell’angolo rotto: la barra degli indirizzi, la console e il resto della pagina sono spesso il posto in cui sta la risposta.
La console e la scheda di rete
La prima cosa che chiede chi sviluppa e l’ultima che la maggior parte delle segnalazioni include. Apri gli strumenti per sviluppatori prima di chiudere la scheda: F12, oppure Cmd + Option + I su un Mac.
Copia il testo dell’errore invece di fotografarlo, così si può cercare, e annota lo stato e il percorso di ogni richiesta fallita.
POST https://example.com/api/auth/login 403 (Forbidden)
Error: Authentication failed: Invalid CSRF token
at login.js:45
L’impatto
La priorità non è la stessa cosa della tua urgenza, e una segnalazione che non offre alcun segnale viene smistata da chi grida più forte. Dai i fatti che permettono a un altro di decidere: quante persone sono coinvolte, se ci sono di mezzo soldi o dati, se esiste un modo per aggirarlo e se prima funzionava.
“Blocca l’accesso a ogni utente Firefox, nessuna soluzione alternativa, iniziato dopo il rilascio di questo pomeriggio” è più allarmante di “urgente”, ed è più probabile che venga preso in carico oggi.
Il modello
# Segnalazione di bug
## Titolo
[Titolo chiaro e descrittivo - cosa non funziona e dove]
## Descrizione
[Breve quadro del problema - 1-2 frasi]
## Passaggi per riprodurre
1. [Primo passaggio - partendo da uno stato noto]
2. [Secondo passaggio - sii preciso sulle azioni]
3. [Terzo passaggio - indica dati e valori usati]
4. [Altri passaggi se servono]
5. [Passaggio finale che provoca il bug]
## Comportamento atteso
[Cosa dovrebbe succedere secondo il design o la logica]
## Comportamento reale
[Cosa succede davvero - descrivi i sintomi]
## Ambiente
- **Browser:** [Nome e versione del browser]
- **Sistema operativo:** [Sistema e versione]
- **Dispositivo:** [Desktop o mobile e modello]
- **Risoluzione dello schermo:** [Se è un problema di layout]
- **Stato utente:** [Autenticato o no, ruolo]
## Prove visive
[Allega screenshot o video]
- Screenshot 1: [Descrizione]
- Screenshot 2: [Descrizione]
- Video: [Link o allegato]
## Errori di console
```
[Incolla gli errori dalla console del browser - F12 → scheda Console]
```
## Problemi di rete
[Chiamate API fallite dalla scheda Rete - F12 → Rete]
## Impatto e gravità
- **Gravità:** [Critica/Alta/Media/Bassa]
- **Utenti coinvolti:** [Tutti / Utenti mobili / Un ruolo specifico / ecc.]
- **Impatto sul business:** [Ricavi persi / Carico di supporto / ecc.]
- **Soluzione alternativa:** [Sì/No - se sì, descrivila]
## Contesto aggiuntivo
- **Frequenza:** [Ogni volta / A volte / Raramente]
- **Da quando:** [Adesso / Dopo un aggiornamento / Da [data]]
- **Ticket collegati:** [Link a bug simili]
- **Altre note:** [Qualsiasi altra informazione utile]
## Lista di controllo
- [ ] Ho provato in un ambiente pulito (finestra in incognito o privata)
- [ ] Ho incluso i passaggi per riprodurre
- [ ] Ho fornito i dettagli dell'ambiente
- [ ] Ho allegato screenshot o video
- [ ] Ho controllato la console per gli errori
- [ ] Ho verificato se il problema era già stato segnalato
Lo stesso bug, segnalato due volte
La prima versione è quella che di solito arriva. La seconda è la stessa persona, lo stesso difetto, quattro minuti dopo.
- Debole
- Login rotto. Non riesco a entrare. Sistematelo per favore!!!
- Meglio
- Il pulsante di accesso non risponde dopo l'inserimento delle credenziali su Firefox 121, Windows 11
La seconda segnalazione porta tutto il resto: i quattro passaggi di sopra, il comportamento atteso e quello reale, Firefox 121 su Windows 11 Pro a 1920x1080 in una finestra privata senza estensioni, due screenshot e una registrazione di quindici secondi, l’errore CSRF dalla console e una riga sulla gravità - tutti gli utenti, nessuna soluzione alternativa, iniziato dopo il rilascio delle 14:30.
Niente di tutto questo ha richiesto ricerche. Era tutto sullo schermo mentre il bug stava succedendo, e ogni singolo pezzo è sparito nel momento in cui la scheda è stata chiusa.
Da dove viene il contesto
Guarda cosa contiene la seconda segnalazione. Il titolo, i passaggi e il comportamento atteso sono giudizio, e quel giudizio è tuo. L’ambiente, lo screenshot, l’errore di console e la richiesta fallita non sono giudizio per niente. Erano fatti sul browser nel momento in cui le cose sono andate storte, e scriverli a mano vuol dire lasciare la pagina, cercare una stringa di versione e ribattere un errore.
Session Replay
Estensione gratuita per Chrome. Un clic sulla pagina che si comporta male cattura lo screenshot, la console e il registro di rete, e ti restituisce un link da incollare nel ticket.
Non scriverà il tuo titolo, non deciderà la tua gravità e non dividerà due difetti in due ticket. Quelle sono le parti che hanno bisogno di una persona che era lì.