Invio di una nuova segnalazione

Scrivere una buona segnalazione di problemi o bug può fare la differenza nella capacità di risolvere un problema. Ecco come inviare una buona segnalazione di bug a {{ nome_formale }}.

Ricerca di problemi esistenti

Prima di inviare un nuovo problema, cercate nell'indice i problemi esistenti che corrispondono al vostro. Se esiste un problema aperto che sembra corrispondere al vostro problema, aggiungete un commento a quel problema con qualsiasi informazione aggiuntiva sulla vostra esperienza. Ad esempio, se il problema si verifica su una versione diversa di Python o su un sistema operativo diverso, queste informazioni aggiuntive possono essere utili per determinare l'impatto o la causa del problema.

Se si trova un problema chiuso che sembra corrispondere al proprio problema, controllare quanto recentemente è stato chiuso. Se il problema è stato chiuso molto di recente, probabilmente significa che il bug è stato risolto e sarà corretto nella prossima versione. Se il problema è stato chiuso più di 4 mesi fa, è probabile che si tratti di un problema diverso, a prescindere dalla somiglianza del messaggio di errore.

Se non trovate un problema che corrisponda a ciò che vedete, potrebbe essere opportuno aprire un nuovo problema.

Iniziare con una discussione

Prima di inviare un problema su GitHub, si consiglia di iniziare con una discussione per chiedere se quello che si sta verificando è effettivamente un bug o un problema con la propria configurazione o processo. A meno che non si riscontri un comportamento che contraddice direttamente quello documentato, è probabile che valga la pena fare una domanda prima di passare direttamente all'invio di una segnalazione di bug. Se si scopre di aver trovato un problema, un argomento di discussione può essere facilmente trasformato in un problema.

Avviare una discussione può anche aiutare a garantire che la segnalazione di un problema avvenga nel posto migliore. Anche se si è riscontrato un problema durante l'utilizzo di {{ nome_formale }}, il problema potrebbe essere causato da un bug in un altro progetto dell'ecosistema BeeWare.

Scrivere una buona segnalazione di bug

Se un nuovo problema è richiesto, è importante fornire il maggior numero di dettagli possibile. Una buona segnalazione di bug include tutte le informazioni potenzialmente correlate al bug, nonché il più piccolo esempio di riproduzione possibile.

L'esempio di riproduzione deve essere il più breve e conciso possibile, pur mostrando il bug. Fornire un esempio enorme rende molto più difficile la risoluzione dei problemi, soprattutto se si basa su altre librerie o richiede una conoscenza approfondita del comportamento previsto o della logica interna dell'esempio.

Abbiamo bisogno di quanti più dettagli possibili. Questi includono, ma non si limitano a:

• La versione del sistema operativo, fino alla versione micro (ad esempio, macOS 15.7.2).
• La vostra versione di Python, anche fino alla versione micro (per esempio, 3.14.1).
• Come avete installato Python. L'avete scaricato da python.org? Avete usato Homebrew? uv? pyenv? conda? Qualcos'altro?
• La versione specifica degli strumenti BeeWare che si sta utilizzando (ad esempio, Toga 0.5.3). Se si utilizza una versione di sviluppo, quale hash Git si sta utilizzando? Non è sufficiente dire "il ramo principale attuale", perché può cambiare ogni giorno.
• Le versioni specifiche di altri pacchetti che devono essere installati per causare il problema. È possibile includere i risultati dell'esecuzione di python -m pip freeze per fornire queste informazioni.
• Se è stato generato un file di log, l'intero file di log.
• Se è stata generata una traccia di stack, l'intera traccia di stack. Non limitatevi a fornire il messaggio di errore finale: il contesto completo della traccia di stack è importante. Inoltre, è meglio fornirla in formato testo, non come screenshot.
• Qualsiasi altro aspetto del computer o della configurazione di rete che possa influire sul problema. Il computer è più vecchio o più lento? Si tratta di un computer di lavoro che potrebbe avere firewall, antivirus o altre restrizioni? La rete è particolarmente lenta? Il sistema operativo viene eseguito con impostazioni predefinite insolite (come ad esempio un carattere molto grande o un'altra tecnologia di assistenza attivata)?

Cercate di pensare fuori dagli schemi e di includere tutto ciò che vi viene in mente e che potrebbe avere un impatto sul problema che state riscontrando. Se ci date più di quello che ci serve, è facile che ignoriamo quello che non ci serve. Non possiamo inventarci qualcosa che avete tralasciato.

Un esempio minimo

La parte più importante di una segnalazione di bug è un caso di riproduzione minimo. Deve essere possibile per una terza persona leggere le istruzioni del caso di riproduzione, seguirle e osservare lo stesso problema. Ciò può significare fornire un progetto di esempio che presenta il problema o, ancora meglio, utilizzare un esempio preesistente (come un tutorial o un progetto di esempio che fa parte della base di codice esistente).

Il vostro progetto completo non è un caso di riproduzione minima. Un caso di riproduzione minimo non deve contenere alcun codice che non sia assolutamente necessario per produrre un problema. Siate spietati nel comporre il vostro caso di riproduzione: se un pulsante non è necessario per risolvere il problema, non includetelo.

Molto spesso il processo di sviluppo di questo caso di riproduzione minimale rivelerà l'origine del problema, perché l'atto di creare l'esempio minimale costringe a capire esattamente quale sia la causa del problema, sia che si tratti di un bug nel codice, sia che derivi da ipotesi errate o dall'uso dell'API.

Dovreste anche essere espliciti in qualsiasi istruzione di riproduzione. Dire "Chiudi l'applicazione di esempio" può significare fare clic sul pulsante di chiusura della finestra, selezionare "quit" da un menu o digitare Control-C in un terminale. Il rapporto non deve lasciare spazio ad ambiguità su ciò che deve essere fatto per riprodurre il problema.

Invio del rapporto

Navigate to the project issues list, click the "New issue" button, and choose "Bug report" to begin the process.

**Il modello viene fornito come suggerimento per aiutarvi a fornire le informazioni necessarie. Ricordate che potete (e dovete!) sempre fornire più informazioni di quelle richieste dal modello, ma come minimo abbiamo bisogno di tutte le informazioni presenti nel modello.

Quando si include il codice, nel caso in cui sia possibile riprodurlo con un esempio esistente, come il tutorial di BeeWare, è possibile fornire un link. Altrimenti, fornire il codice nella relazione. Il codice deve essere formattato in Markdown; un blocco di codice deve avere tre backtick (```) prima e dopo.

Se è necessario includere un lungo blocco di testo, è possibile renderlo contenuto collassato utilizzando la seguente sintassi:

<details>
<summary>Collapsed content title</summary>
Long block of text.
</details>

Dopo aver fornito tutte le informazioni possibili, fare clic su "Crea" per inviare il rapporto.