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.
Se sei qui solo per il modello
Ci sono tre modi per averlo, e ognuno va bene in un momento diverso.
Da compilare subito, sta sul sito come modello di segnalazione bug da compilare. Percorri i campi nella pagina e copi la segnalazione finita in Markdown o in testo semplice, che è la strada più rapida quando hai un bug davanti e un ticket che lo aspetta.
Come file di testo è il download che sta più in basso in questa pagina, accanto al modello. Tienilo accanto al tuo gestore delle segnalazioni: gli stessi campi senza nessun sito attorno, che è quello che serve se il modello deve stare in un repository, in un wiki o in un modulo per le issue.
La versione annotata sta più in basso in questa pagina, nella sezione Il modello. Lì ogni campo porta una nota tra parentesi quadre che dice cosa ci va dentro, ed è quella da leggere se stai decidendo cosa deve chiedere la tua squadra invece di compilare una singola segnalazione.
Una cosa vale la pena saperla prima di consegnarne una a una squadra. Il modello chiede sette cose in un ordine fisso, e le sezioni che stanno fra qui e lui spiegano a cosa serve ognuna. Un modello dato a persone che non si sono accordate sul perché i campi esistono torna compilato a metà, che è esattamente il fallimento che doveva evitare.
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ì.