Documentazione di PostgreSQL 9.0 > Prefazione > Linee guida per la segnalazione di bug
PrecedenteUlteriori informazioniIl gruppo di lavoro per la traduzione in italianoSuccessivo

5. Linee guida per la segnalazione di bug

Quando vengono trovati bug in PostgreSQL™ vogliamo saperlo. Le segnalazioni di bug giocano un ruolo importante nel rendere PostgreSQL™ più attendibile, perchè anche la massima attenzione non può garantire che ogni parte di PostgreSQL™ funzionerà su ogni piattaforma in ogni circostanza.

I seguenti suggerimenti sono intesi ad assistere nella creazione di segnalazioni di bug che possando essere gestite con efficacia. Non è richiesto seguirli ma farlo costituirà un vantaggio per tutti.

Non possiamo promettre di risolvere subito ogni bug. Se il bug è evidente, critico, o coinvolge molti utenti, ci sono buone possibilità che qualcuno se ne occupi. Potrebbe anche capitare che venga consigliato di aggiornare ad una versione più recente per vedere se il bug si ripresenta. O potremmo decidere che il bug non possa essere risolto prima che venga completata riscrittura importante. O forse è semplicemente troppo difficile e ci sono cose più importanti in agenda. Se si ha bisogno di aiuto istantaneo, considerare un contratto di supporto commerciale.

5.1. Identificare i bug

Prima di segnalare un bug, preghiamo di leggere e ri-leggere la documentazione per verificare se sia possibile veramente fare quello che stai provando. Se dalla documentazione non è chiaro se si possa fare qualcosa o no, preghiamo di segnare anche questo; È un bug della documentazione. Se si dimostra che un programma fa qualcosa di differente da quello che dice la documentazione, quello è un bug. Questo potrebbe includere, ma non essere limitato a, le seguenti circostanze:

  • Un programma termina con un segnale fatale o un messaggio di errore del sistema operativo che indica un problema nel programma. (Un esempio opposto potrebbe essere un messaggio di «disco pieno», dato devi risolvere il problema da solo.)

  • Un programma produce l'output sbagliato per ogni input fornito.

  • Un programma si rifiuta di accettare input validi (come definiti nella documentazione).

  • Un programma accetta input non validi senza notifica o messaggio di errore. Tenere a mente che l'idea che si ha di input non valido potrebbe essere per noi un'idea per un'estensione o per compatibilità con la pratica tradizionale.

  • PostgreSQL™ non riesce a compilare, fare il build, o installarsi, secondo le istruzioni per le piattaforme supportate.

«Programma» si riferisce ad ogni eseguibile, non solo al server backend.

L'essere lento o l'accaparrare risorse non è necessariamente un bug. Leggere la documentazione o chiedere su una delle mailing list per la messa a punto delle applicazioni. Nemmeno fallire nel soddisfare lo standard SQL è necessariamente un bug, a meno che la conformità per la specifica caratteristica sia esplicitamente richiesta.

Prima di continuare, controllare sull'elenco TODO nelle FAQ per vedere se il bug è già noto. Se non si riesce a decifrare le informazioni dell'elenco TODO, riportare il problema. Il minimo che possiamo fare è rendere l'elenco TODO più chiaro.

5.2. Cosa segnalare

La cosa più importante da ricordare sulla segnalazione di bug è di esporre tutti i fatti e solo i fatti. Non supporre quello che si pensa sia andato male, cosa «è sembrato essere successo», o quale parte del programma ne abbia colpa. Se non si ha familiarità con l'implementazione probabilmente supporrai sbagliato e non ci aiuterai. Ed anche se si ha, spegazioni educate sono un ottimo supplemento ma non sostituiscono i fatti. Se boddiamo risolvere il bug dovremmo comunque vederlo accadere, prima. Segnalare i fatti è relativamente semplice (probabilmente si potrà copiarli e incollarli dallo schermo) ma molto spesso vengono tralasciati importanti dettagli perchè si pensa non siano importanti o che la segnalazione sia comunque comprensibile.

I seguenti punti dovrebbero essere contenuti in ogni segnalazione di bug:

  • L'esatta sequenza di passi dall'avvio del programma necessaria a generare il problema. Questo dovrebbe essere autonomo; non è sufficiente fornire una sola istruzione SELECT senza la CREATE TABLE precedente e le istruzioni INSERT, se l'output dovrebbe dipendere dai dati nelle tabelle. Non abbiamo il tempo per eseguire del "reverse-engineering" sullo schema del database, e se dobbiamo utilizzare i nostri dati probabilmente perderemo il problema.

    Il miglior formato per un test su problemi relativi all'SQL è un file che può essere eseguito attraverso il frontend psql. (Assicurarsi di non avere niente nel file si avvio ~/.psqlrc.) Un modo semplice per creare questo file è usare pg_dump per eseguire un dump delle dichiarazioni delle tabelle e dei dati necessari a impostare la scena, quindi aggiungere la query che dà problemi. Si incoraggia a minimizzare la dimensione del proprio esempio, ma questo non è assolutamente necessario. Se il bug è riproducibile, lo troveremo in ogni caso.

    Se la propria applicazione usa qualche altra interfaccia client, tipo PHP, allora preghiamo di provare a isolare le query colpevoli. Probabilmente non metteremo su un server web per riprodurre il vostro problema. In ogni caso, ricordarsi di fornire i file di input esatti; Non presumere che il problema succeda con «file grandi» o «database di medie dimensioni», ecc. dato che queste informazioni sono troppo inesatte per essere d'aiuto.

  • L'output ottenuto. Per favore, non dire che «non ha funzionato» o «si è bloccato». Se c'è un messaggio di errore, mostrarlo, anche se non lo si capisce. Se il programma termina con un errore del sistema operativo, dire quale. Se non succede niente, dirlo. Anche se il risultato del tuo test è un crash del programma, potrebbe non succedere sulla nostra piattaforma. La cosa più semplice da fare è copiare l'output dal terminale, se possibile.

    [Nota]

    Nota

    Se si sta segnalando un messaggio di errore, per favore fornire la forma più prolissa del messaggio. In psql, dare un'occhiata prima di tutto a \set VERBOSITY verbose. Se si sta estraendo il messaggio dal log del server, impostare il parametro log_error_verbosity a verbose così che tutti i dettagli siano riportati nel log.

    [Nota]

    Nota

    In caso di errori fatali, il messaggio di error riportato dal client potrebbe non contenere tutte le informazioni disponibili. Per favore, controllare anche l'output del log del server database. Se non si tiene traccia dell'output del log del server, questo potrebbe essere un buon momento per iniziare a farlo.

  • È molto importante specificare l'output che ci si aspettava. Se si scrive solo «Questo comando dà questo output.» o «Questo non è cosa mi aspettavo.», potremmo lanciarlo, osservare l'output, e pensare che sia giusto ed esattamente quello che ci aspettavamo. Non dovremmo spendere del tempo cercando di decifrare l'esatta semantica dei tuoi comandi. Trattenersi specialmente dal dire semplicemente che «Questo non è quello che dice l'SQL/l'Oracle fa.» Scavare per avere il corretto comportamento dall'SQL non è un compito divertente, e non sappiamo nemmeno come tutti gli altri database si comportano. (Se il problema è un crash del programma, si può ovviamente omettere questo elemento.)

  • Qualsiasi opzione a linea di comando ed altre opzioni di avvio, inclusa ogni variabile d'ambiente rilevante o file di configurazione che sono stati cambiati rispetto ai predefiniti. Inoltre, si prega di fornire informazioni esatte. Se si sta usando una distribuzioni pacchettizata che avvia il server database all'avvio, si dovrebbe provare a capire in che modo viene fatto.

  • Qualsiasi cosa sia stata fatta diversamente dalle istruzioni di installazione.

  • La versione di PostgreSQL™. È possibile eseguire il comando SELECT version(); per scoprire la versione del server alla quale si è connessi. La maggior parte dei programmi eseguibili supportano anche un'opzione --version; almeno postgres --version e psql --version dovrebbero funzionare. Se la funzione o le opzioni non esistono allora la versione è abbastanza vecchia da meritare un aggiornamento. Se si sta utilizzando una versione pacchettizzata, tipo RPM, includere ogni sottoversione che il pacchetto potrebbe avere. Se ci si riferisce a uno snapshot CVS, menzionarlo, includendo la sua data e orario.

    Se la versione è più vecchia di 9.0 quasi certamente diremo di aggiornarla. Vengono risolti molti bug e ci sono miglioramenti in ogni nuova versione, così è possibile che un bug riscontrato in una versione più vecchia sia già stato risolto. Possiamo fornire sono un supporto limitato per siti che usano vecchie versioni di PostgreSQL™; Se si ha bisogno di più di quello che possiamo fornire, considerare l'acquisto un contratto di supporto commerciale.

  • Informazioni sulla piattaforma. Queste includono il nome e la versione del kernel, della libreria C, processore, informazioni sulla memoria, e così via. Nella maggior parte dei casi, è sufficente segnalare distributore e versione, ma non dare per scontato che chiunque sappia esattamente cosa contiene «Debian» e che chiunque usi un i386. Se si hanno problemi di installazione, allora saranno necessarie anche informazioni sulla toolchain della macchina (compilatore, make e così via)

Non aver paura se la segnalazione di bug diventa lunga. È normale. È meglio segnalare ogni cosa subito che costringerci a tirar fuori i fatti per voi. D'altra parte, se i file in input sono enormi, è saggio chiedere prima se qualcuno è interessato a guardarci. Ecco un articolo che evidenzia ulteriori consigli per la segnalazione di bug.

Non spendere tutto il tempo a capire quali cambiamenti in input fanno sparire il problema. Probabilmente questo non aiuterà a risolverlo. Se viene dimostrato che il bug non può essere risolto subito, si avrà comunque il tempo per trovare e condividere il proprio "work-around". Inoltre, non perdere tempo tentando di capire perchè esiste il bug. Noi lo scopriremo abbastanza velocemente.

Quando si scrive una segnalazione di bug, preghiamo di evitare terminologia confusa. Il pacchetto software completo si chiama «PostgreSQL», a volte in breve «Postgres». Se si sta parlando specificatamente del server backend, menzionarlo, non dire semplicemente «PostgreSQL si blocca». Un crash di un singolo processo del server backend è abbastanza diverso dal crash del processo padre «postgres»; Per favore, non dire «il server si è bloccato» quando si intende che un singolo processo di backend è caduto, e nemmeno viceversa. Inoltre, i programmi client, tipo il frontend interattivo «psql», sono completamente separati dal backend. Preghiamo di provare ad essere specifici sul fatto che il problema sia sul lato client o server.

5.3. Dove segnalare i bug

In generale, mandare segnalazioni di bug alla mailing list . È richiesto usare un oggetto descrittivo per il messaggio email, per esempio parte del messaggio di errore.

Un altro metodo è quello di riempire il modulo online disponibile sul sito web del progetto FAre una segnalazione di bug in questo modo fa sì che venga mandata per email alla mailing list .

Se la segnalazione di bug ha implicazioni di sicurezza e si preferisce che non diventi visibile immediatamente negli archivi pubblici, non mandarla a pgsql-bugs. Questioni di sicurezza possono essere riportate privatamente a .

Non mandare segnalazioni di bug a tutti gli utenti delle mailing list, tipo o . Queste mailing list servono a rispondere alle domande degli utenti, e i loro iscritti normalmente non desiderano ricevere segnalazioni di bug. In più, molto probabilmente non saranno capaci di risolverli.

Inoltre, preghiamo di non mandare segnalazioni alla mailing list degli sviluppatori . Questa lista è per discutere lo sviluppo di PostgreSQL™, e sarebbe utile mantenere separate le segnalazioni di bug. Potremmo scegliere di avere una discussione su una segnalazione di bug su pgsql-hackers, se il problema necessita più analisi.

Si si ha un problema con la documentazione, il miglior posto dove segnalarlo è la mailing list sulla documentazione . Preghiamo di essere specifici su quale parte della documentazione crea problemi. with.

Se il bug è un problema di portabilità su una piattaforma non standard, manda la segnalazione a , così noi (e tu) possiamo lavorare sul porting di PostgreSQL™ sulla tua piattaforma.

[Nota]

Nota

Dato lo spiacevole ammontare di spam in giro, tutte le mailing list citate sopra sono mailing list chiuse. Così. è necessario iscriversi a una lista per poterci scrivere. (Comunque, non devi essere iscritto se si usa il form online per la segnalazione di bug). Se si desidera mandare una email ma non si vuole ricevere il traffico della lista, ci si può iscrivere ed impostare la propria opzione di iscrizione si nomail. Per maggiori informazioni mandare una email a con la sola parola help nel corpo del messaggio.

Documentazione di PostgreSQL 9.0 > Prefazione > Linee guida per la segnalazione di bug
PrecedenteUlteriori informazioniIl gruppo di lavoro per la traduzione in italianoSuccessivo