Utilizzo degli strumenti

Uno dei feedback più preziosi che possiamo ricevere è quello delle persone che provano a utilizzare gli strumenti BeeWare e scoprono che c'è un punto di attrito o una funzionalità mancante. È incredibilmente utile per noi capire le difficoltà che si possono incontrare quando si utilizzano gli strumenti per scopi reali.

Pensate alla cosa che avete sempre voluto costruire e provate a farlo. Se si scopre che si è in grado di costruire il proprio progetto, congratulazioni! Avete la cosa che avete sempre desiderato.

Tuttavia, se non riuscite, fateci sapere cosa è andato storto. Mancava una funzione? La documentazione è confusa o carente in qualche aspetto? Condividere la vostra esperienza ci fornisce utili indicazioni che possiamo utilizzare per modellare il nostro processo di pianificazione.

Se si verificano problemi, aprire un nuovo argomento di discussione, poiché potrebbe essere l'inizio di un nuovo problema o di una proposta di funzionalità.

Utilizzo dello strumento di contribuzione

Invia 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.

Proponi una nuova funzionalità

Hai un'idea su un miglioramento per {{ nome_formale }} - come si fa a sottoporre l'idea alla vostra attenzione?

Fate la vostra ricerca

Il primo passo consiste nel cercare nell'issue tracker {{ nome_formale }} i problemi di funzionalità (problemi etichettati come "miglioramento"), documentation issues (problemi con tag "documentation"), o Discussioni per vedere se l'idea è già stata proposta in precedenza. In caso affermativo, se avete un nuovo contesto o nuove idee da aggiungere, inseritele nella discussione esistente. Se si desidera assistenza per la ricerca, è possibile chiedere nel canale #dev su BeeWare Discord. Potremmo essere in grado di indirizzarvi verso le discussioni esistenti, di fornirvi un contesto di cui potreste non essere a conoscenza o di collegare la vostra idea a un'altra che potrebbe non sembrare immediatamente collegata.

Discutere l'idea

Se non si trovano riferimenti esistenti alla propria idea, avviare una Discussione. Fornire una descrizione di alto livello dello scopo e del caso d'uso della propria idea. Includere qualsiasi idea sull'aspetto della funzionalità, se implementata, come la forma generale di un'API, l'aspetto visivo di una funzionalità o il documento che verrebbe aggiunto. Se applicabile, è necessario includere anche qualsiasi ricerca effettuata su come la vostra idea si manifesterebbe su piattaforme diverse.

Una volta aperto il thread di discussione, il team BeeWare e il resto della comunità risponderanno. Il team centrale cercherà di fornire almeno un'impressione iniziale della vostra idea entro due giorni lavorativi. Se un'idea è particolarmente complessa, un'analisi più dettagliata potrebbe richiedere fino a una settimana. Eventi come vacanze e conferenze potrebbero allungare leggermente i tempi.

Questa è l'occasione per partecipare a una conversazione sulla vostra idea. Potremmo chiedervi ulteriori dettagli o un contesto. Anche altri membri della comunità possono partecipare alla discussione, fornendo altre prospettive, suggerimenti o controproposte. L'esito della discussione determinerà i passi successivi.

È importante capire che non tutte le idee saranno accettate. Il motivo per cui questo processo inizia con una proposta è che si evita di fare tutto il lavoro per poi scoprire che la modifica non sarà accettata.

Questo non significa che non fosse una buona idea! Ci possono essere ragioni tecniche per cui non può essere implementata. Ad esempio, potremmo rifiutare un'idea se:

• Sarebbe difficile o impossibile da implementare in modo affidabile su tutte le piattaforme supportate; oppure
• Sarebbe difficile da mantenere o la manutenzione richiederebbe l'accesso a tecnologie o software non ampiamente disponibili; oppure
• Serve un pubblico di nicchia, ma impone un notevole sovraccarico agli altri utenti.

Se decidiamo che la vostra idea non è adatta, non significa necessariamente che dobbiate rinunciarvi. Se da un lato possiamo rifiutare un'idea specifica, dall'altro potremmo essere molto più disponibili ad aggiungere un'interfaccia per i plugin o altri punti di estensione che permettano di mantenere la stessa funzionalità come libreria esterna. In questo modo si può avere la funzione, ma senza che i problemi specifici di manutenzione o le limitazioni della funzione diventino un vincolo per il progetto stesso.

Convertite in una richiesta formale di funzionalità

Una volta che la discussione ha raggiunto un consenso sulla forma di una caratteristica, si può creare un nuovo [issue di richiesta di caratteristica] (https://github.com/beeware/{{ nome_progetto }}/issues/new/choose), nell'issue tracker {{ nome_formale }}, che riassume la discussione, collegandosi alla discussione per il contesto.

Non è necessario implementare da soli la propria proposta di funzionalità; è possibile aprire un problema con i dettagli di ciò che si sta proponendo. Tuttavia, la semplice pubblicazione del problema non significa che verrà implementato per voi. Dovrete aspettare che la proposta venga presa in considerazione da qualcun altro interessato alla stessa funzionalità, che si tratti di un altro membro della comunità o del team centrale; tuttavia non è garantito che ciò accada. Se si desidera un'implementazione garantita, è necessario implementarla da soli o pagare qualcun altro per farlo.