Perché citare gli ID dei bug nelle note delle patch può essere considerato una cattiva pratica?

Secondo me, è una buona pratica, supponendo che i tuoi utenti abbiano accesso in lettura al tuo database di bug. Ci sono molte volte in cui le persone sono in attesa di un determinato bug da correggere per decidere quando eseguire l'aggiornamento.

Penso che ciò che è disapprovato sia solo che cita l'id del bug e nient'altro. Dovresti sempre fornire anche una descrizione comprensibile senza andare al bug tracker. Ciò ti consente anche di cambiare i bug tracker in futuro senza invalidare completamente le tue precedenti note di rilascio.

È, come detto nel commento citato ... scortese.

Scortesemente con te stesso

Immagina il seguente scenario. Stai visualizzando i log nel controllo del codice sorgente. Ti stai chiedendo cosa è cambiato un commit. Invece di spiegarlo in inglese, ti dice:

Solved #1307

Esegui il sistema di tracciamento dei bug, sperando di avere qualcosa di utile. Il bug # 1307 è stato segnalato come risolto. Nella descrizione, vedi:

Same bug as #1284

Grazie, è molto utile. Ora devi passare al rapporto bug # 1284 per leggere che si tratta di un duplicato del bug # 1113 che si riferisce ai bug # 1112, # 1065 e # 1067.

Cinque minuti dopo, non hai idea di cosa stai cercando all'inizio.

Un messaggio di registro di controllo della versione molto più utile potrebbe essere:

Solved an issue with the users being unable to log on with a password longer than 25 characters (see #1307), by removing applying the same password length policy to the data access layer as the one used in the website itself.

Allo stesso modo, nel sistema di tracciamento dei bug, il report # 1307 potrebbe essere più autoesplicativo , ricordando di quale era la segnalazione bug # 1284 e come la nuova è diversa da quello vecchio.

Scortese con i clienti

Questo non è l'unico problema di cordialità.

Un altro è che facendo riferimento troppo senza ulteriori informazioni, stai rendendo le note delle patch / i registri di controllo della versione / i rapporti del sistema di tracciamento dei bug inutilizzabili per qualcuno che non ha molta familiarità con quei sistemi . Quando ti occupi quotidianamente di un sistema di tracciamento dei bug, sai come navigare rapidamente nei report, visualizzare più report fianco a fianco, ecc. Quando sei un cliente senza background tecnico, puoi facilmente perderlo.

Anche in questo caso, i messaggi più dettagliati sono molto utili di un semplice riferimento. Nota che vuoi ancora mantenere i riferimenti: nulla è più sbagliato di un bug che è lo stesso di un bug che hai incontrato due settimane fa, ma non ricordare il suo ID.

Come nota, lo stesso problema esiste in molte giurisdizioni. In Francia, ad esempio, non è insolito che una legislazione faccia riferimento a più fonti, che nel frattempo potrebbero cambiare. Ciò significa che per capirlo completamente, devi passare ore a volte in una biblioteca, cercando dozzine di testi di riferimento, ogni testo ha i suoi riferimenti agli altri.

Non c'è niente di sbagliato nel citare i numeri dei numeri nelle note delle patch, a condizione che gli utenti possano leggere il problema che viene citato. Se il database dei bug consente a chiunque di leggere, citare il numero di bug può essere davvero molto utile. (È preferibile, se le note delle patch sono in un formato che consente i collegamenti, rendere tali ID di problema come link al problema in questione.) Ciò non significa che dovresti esporre tutti i problemi al pubblico in generale; può ancora essere utile avere quelli che sono protetti (ad es., dove hanno le password live!)

Citando un numero di problema in cui la persona che legge non può andare a cercare i dettagli e la cronologia del bug, è abbastanza ostile. Non che citare tali problemi senza l'ID del problema sia molto più amichevole.

Dipende ovviamente da chi sono le persone che leggeranno le note sulle patch e dagli utenti target del software.

Ma nella maggior parte dei casi, la stragrande maggioranza dei tuoi utenti semplicemente non si preoccupa su quale sia l'ID del bug. A loro non importa perché è stato rotto, quale è la correzione, o qualsiasi altra cosa - vogliono solo sapere cosa è cambiato con una descrizione testuale molto succinta senza dover andare su un'altra pagina per ogni cambiamento.

Citare gli ID dei bug mi fa fermare e pensare, e io - come utente - non voglio pensare. È una sorta di problema di usabilità.

Dai un'occhiata ad esempio al registro modifiche di Visual Assist X . Tutti gli ID dei bug collegati sono solo rumore che mi distrae dalla comprensione di ciò che è cambiato. E questo è un add-on per Visual Studio, rivolto ai programmatori. E io sono un programmatore. Se questo mi infastidisce, immagina l'utente medio che non sa nemmeno cosa sia un bug tracker ..

PS: ero l'autore del commento che ha suscitato la domanda

Un ID bug è obbligatorio per un punto di riferimento . I motivi:

• Impedisci ambiguità: due o più bug potrebbero avere descrizioni simili. Quindi bisognerebbe un ancoraggio per distinguere tra loro.
• Praticità : quando si discute di un bug, sia con un cliente che internamente, l'ID del bug viene spesso utilizzato come forma abbreviata. Se l'ID verrà omesso dalle note delle patch, sarà difficile discuterne:

3052 was already fixed, still working on 3077

è più conveniente di:

The "application crash on apply button" was fixed, still working on the "NullReferenceException on clicking change user"

Direi che dipende dal tuo sistema: sono fortunato che quello che uso rileva automaticamente tali riferimenti nei messaggi di commit e aggiunge un link al ticket memorizzato nel bug tracker, quindi non è un problema.

Ma se fossi su un sistema in cui non è disponibile, menzionerei ancora l'ID del ticket (in questo modo puoi cercare rapidamente nei log per ID ticket ) insieme a una breve descrizione di cosa il bug è.