Risoluzione di un problema¶

{{ nome_formale }} tiene traccia di un elenco di [problemi noti] (https://github.com/search?q=org%3Abeeware%20is%3Aopen%20is%3Aissue%20label%3Abug&type=issues). Tutti questi problemi sono candidati a essere risolti.

Questo elenco può essere filtrato in vari modi. Ad esempio, si può filtrare per piattaforma, in modo da concentrarsi sui problemi che riguardano le piattaforme su cui si è in grado di eseguire i test; oppure si può filtrare per tipo di problema, ad esempio documentation bugs. C'è anche un filtro per buoni primi numeri - questi sono problemi che sono stati identificati come problemi con una causa nota e riteniamo che la soluzione dovrebbe essere relativamente semplice (anche se potremmo sbagliarci nella nostra analisi).

Se un problema risale a più di 6 mesi fa, è possibile che sia stato risolto, quindi il primo passo è verificare che sia possibile riprodurre il problema. Utilizzare le informazioni fornite nella segnalazione del bug per cercare di riprodurre il problema. Se non si riesce a riprodurre il problema, segnalare quanto riscontrato come commento al problema e scegliere un altro problema.

Se riuscite a riprodurre il problema, cercate di risolverlo! Scoprite quale combinazione di codice implementa la funzione e cercate di capire cosa non funziona correttamente.

Anche se non riuscite a risolvere il problema, vale la pena di segnalare tutto ciò che scoprite durante il processo come commento al problema. Se riuscite a trovare l'origine del problema, ma non la soluzione, spesso questa conoscenza sarà sufficiente per risolvere il problema da parte di chi conosce meglio la piattaforma. Se il problema non fornisce già un buon caso di riproduzione (una piccola applicazione di esempio che non fa altro che riprodurre il problema), fornirne uno può essere di grande aiuto.

Contribuire alla correzione di un problema¶

Configurare un ambiente di sviluppo

Contribuire a {{ nome_formale }} richiede la creazione di un ambiente di sviluppo.

Prerequisiti¶

È necessario installare i seguenti prerequisiti.

macOSLinuxWindows

{{ nome_formale }} richiede Python 3.10+. È necessario anche un metodo per gestire gli ambienti virtuali (come venv).

È possibile verificare la versione di Python installata eseguendo:

Python 3.8.10 (versione predefinita, 20 luglio 2020, 16:16:00)

Se è installata più di una versione di Python, potrebbe essere necessario sostituire python3 con un numero di versione specifico (ad esempio, python3.13).

Si consiglia di evitare le versioni di Python rilasciate di recente (cioè quelle che hanno un micro numero di versione ".0" o ".1", come ad esempio 3.14.0). Questo perché gli strumenti necessari per supportare Python su macOS spesso non sono disponibili per le versioni stabili di Python rilasciate di recente.

{{ nome_formale }} richiede Python 3.10+. È necessario anche un metodo per gestire gli ambienti virtuali (come venv).

È possibile verificare la versione di Python installata eseguendo:

Python 3.8.10 (versione predefinita, 20 luglio 2020, 16:16:00)

Se è installata più di una versione di Python, potrebbe essere necessario sostituire python3 con un numero di versione specifico (ad esempio, python3.13).

Si consiglia di evitare le versioni di Python rilasciate di recente (cioè quelle che hanno un micro numero di versione ".0" o ".1", come ad esempio 3.14.0). Questo perché gli strumenti necessari per supportare Python su Linux spesso non sono disponibili per le versioni stabili di Python rilasciate di recente.

{{ nome_formale }} richiede Python 3.10+. È necessario anche un metodo per gestire gli ambienti virtuali (come venv).

È possibile verificare la versione di Python installata eseguendo:

C:\...>py -3 --version

Se è installata più di una versione di Python, potrebbe essere necessario sostituire la -3 con un numero di versione specifico (ad esempio, -python{{ versione_python_recente }}).

Si consiglia di evitare le versioni di Python rilasciate di recente (cioè quelle che hanno un micro numero di versione ".0" o ".1", come ad esempio 3.14.0). Questo perché gli strumenti necessari per supportare Python su Windows spesso non sono disponibili per le versioni stabili di Python rilasciate di recente.

Impostare il proprio ambiente di sviluppo¶

Il modo consigliato di impostare l'ambiente di sviluppo per {{ nome_formale }} è quello di usare un ambiente virtuale, e quindi installare la versione di sviluppo di {{ nome_formale }} e le sue dipendenze.

Clonare il repository {{ nome_formale }}¶

Quindi, andare alla pagina {{ nome_formale }} su GitHub e, se non lo si è già fatto, fare un fork del repository nel proprio account. Quindi, fare clic sul pulsante "<> Codice" sul proprio fork. Se sul computer è installata l'applicazione desktop di GitHub, si può selezionare "Apri con GitHub Desktop"; altrimenti, copiare l'URL HTTPS fornito e usarlo per clonare il repository sul computer usando la riga di comando:

macOSLinuxWindows

Eseguire il fork del repository {{ nome_formale }} e poi:

$ git clone https://github.com/<il tuo nome utente>/beeware.git

(sostituendo il proprio nome utente GitHub)

Eseguire il fork del repository {{ nome_formale }} e poi:

$ git clone https://github.com/<il tuo nome utente>/beeware.git

(sostituendo il proprio nome utente GitHub)

Eseguire il fork del repository {{ nome_formale }} e poi:

C:\...>git clone https://github.com/<il tuo nome utente>/beeware.git

(sostituendo il proprio nome utente GitHub)

Imposta un repository upstream¶

Dopo aver clonato il tuo fork, aggiungi il repository BeeWare come upstream remoto. Questo fornisce al tuo clone locale un riferimento al repository originale, rendendo più facile sincronizzare gli aggiornamenti nel tempo.

Avrai anche bisogno dei tag da upstream in modo che strumenti come Toga e Briefcase possano risolvere i numeri di versione accurati:

macOSLinuxWindows

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

C:\...>git remote add upstream https://github.com/beeware/beeware.git
C:\...>git fetch --tags upstream

Se desideri che anche la tua fork includa tali tag, puoi inserirli:

$ git push --tags

Questo può essere utile se in seguito crei un nuovo clone e desideri che i tag siano disponibili dal tuo fork.

Creare un ambiente virtuale¶

Per impostare un ambiente virtuale e aggiornare pip, eseguire:

macOSLinuxWindows

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

Il prompt dovrebbe ora avere un prefisso (.venv) davanti.

Installare {{ nome_formale }}¶

Ora che si dispone del codice sorgente, si può eseguire una installazione modificabile di {{ nome_formale }} nel proprio ambiente di sviluppo. Eseguite il seguente comando:

macOSLinuxWindows

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

Abilita il pre-commit¶

{{ nome_formale }} usa uno strumento chiamato pre-commit per identificare semplici problemi e standardizzare la formattazione del codice. Lo fa installando un hook git che esegue automaticamente una serie di code linters prima di finalizzare qualsiasi commit git. Per abilitare il pre-commit, eseguire:

macOSLinuxWindows

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

Ora siete pronti per iniziare l'hacking su {{ nome_formale }}!

Lavora da una filiale

Prima di iniziare a lavorare sulle modifiche, assicurarsi di aver creato un ramo. Per impostazione predefinita, quando si clona il fork del repository, il check-out viene effettuato sul ramo main. Questo è una copia diretta del ramo main di {{ nome_formale }}.

Sebbene sia possibile inviare una richiesta di pull dal proprio ramo main, è preferibile non farlo. Se si invia una richiesta di pull che è quasi corretta, il membro del core team che esamina la richiesta di pull può essere in grado di apportare le modifiche necessarie, piuttosto che dare un feedback chiedendo una modifica minore. Tuttavia, se si invia la richiesta di pull dal ramo `main', ai revisori viene impedito di apportare modifiche.

Lavorare dal ramo principale rende difficile anche per lui dopo aver completato la prima richiesta di pull. Se si vuole lavorare su una seconda richiesta di pull, è necessario avere una copia "pulita" del ramo principale del progetto upstream su cui basare il secondo contributo; se si è fatto il primo contributo dal proprio ramo main, non si ha più a disposizione quella versione pulita.

Si dovrebbero invece apportare le modifiche in un ramo di funzionalità. Un ramo di funzionalità ha un nome semplice per identificare la modifica apportata. Per esempio, se si sta correggendo un bug che causa problemi di compilazione su Windows 11, si potrebbe creare un ramo di funzionalità fix-win11-build. Se il bug si riferisce a un problema specifico che è stato segnalato, è anche comune fare riferimento al numero del problema nel nome del ramo (ad esempio, fix-1234).

Per creare un ramo di funzionalità fix-win11-build, eseguire:

macOSLinuxWindows

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build

Riproduci il problema

Non si può risolvere un problema se non si ha il problema stesso. Pertanto, riprodurre il problema è un prerequisito per risolverlo. Nel software, i problemi sono comunemente chiamati "bug", mentre i problemi sono spesso chiamati "segnalazioni di bug".

Qualcuno ha fornito una segnalazione di bug. È necessario verificare che i passaggi descritti dal segnalatore producano il bug segnalato. È possibile riprodurre lo stesso risultato facendo esattamente ciò che è stato descritto nella segnalazione? Se non ci riuscite, dovete capire perché.

Bug nel codice¶

In una situazione ideale, si avrà la stessa configurazione della persona che ha segnalato il bug, si seguiranno i passaggi e si riuscirà a riprodurre il bug come descritto. In molti casi, però, non sarà così semplice. Molte segnalazioni di bug includono solo spiegazioni vaghe e una serie di condizioni vaghe. Il problema è che molti bug variano in base all'insieme di condizioni coinvolte, tra cui le modalità di interazione, le varie precondizioni, il sistema operativo, la versione del sistema operativo, l'architettura della CPU o il fatto che la macchina dell'utente sia vecchia e lenta o nuova e veloce. Più informazioni abbiamo sulla situazione che circonda il bug, meglio è. Cercate di riprodurre l'insieme di condizioni fornite dal segnalatore. Se non si riesce a farlo, il passo successivo potrebbe essere quello di richiedere ulteriori informazioni alla persona che ha segnalato il bug.

Il modo migliore per riprodurre un bug è con l'esempio più piccolo possibile che presenti comunque il problema. La maggior parte delle volte i segnalatori non forniranno un esempio minimo fattibile; se forniscono un qualsiasi esempio, sarà copiato direttamente dalla loro applicazione del "mondo reale". Il vostro obiettivo sarà quello di ridurre il rapporto alla forma più semplice possibile che mostri il problema. Il miglior caso di riproduzione è il programma più piccolo possibile. Questa riduzione è di per sé utile perché determina quale sia il problema effettivo. Chiunque può prendere l'esempio minimo, eseguirlo e osservare il bug descritto.

Bug nella documentazione¶

I bug nella documentazione possono manifestarsi in modi diversi. Ci sono problemi di formattazione che causano problemi di rendering. A volte non si tratta nemmeno di un bug; la persona potrebbe aver letto male la documentazione o aver commesso un vero e proprio errore. Questo non significa necessariamente che non ci sia un problema nella documentazione. Il contenuto può essere poco chiaro o impreciso, lasciando spazio a confusione o interpretazioni errate. È possibile che un concetto che dovrebbe essere discusso non lo sia, perché è completamente privo di documentazione.

Quando viene segnalato un bug per un problema di documentazione, è necessario verificare che il problema segnalato esista effettivamente. Nel caso di problemi di rendering, è necessario costruire la documentazione per vedere se è possibile riprodurre il problema. Per i problemi relativi ai contenuti è necessario verificare che nessuno abbia inviato un aggiornamento.

Aggiornare il problema¶

La fase finale del processo di triage consiste nel documentare le proprie scoperte lasciando un commento sul problema.

Se siete in grado di riprodurre il problema esattamente come descritto, è tutto ciò che dovete dire. Lasciate un commento dicendo che avete confermato di riscontrare lo stesso problema, nel modo esatto descritto dal segnalatore originale.

Se siete in grado di fornire un contesto aggiuntivo, includete i dettagli di tale contesto. Ad esempio, è possibile riprodurre il problema su un sistema operativo diverso o con una versione diversa di alcuni dei software coinvolti, o qualsiasi altra cosa che differisca dalla segnalazione originale.

Se il rapporto originale mancava di dettagli necessari per riprodurre il rapporto, includere questi dettagli. Ad esempio, si possono fornire dettagli sul sistema operativo o sulla versione che il report originale non ha fornito, registri o tracce di stack più completi o istruzioni più chiare sull'esatta sequenza di operazioni necessarie per riprodurre il problema. Se avete sviluppato un modo più semplice per riprodurre il problema (o il segnalatore originale non ha fornito un caso di riproduzione), potete includere i dettagli di tale metodologia di riproduzione.

Se non riesci a riprodurre il problema, lascia comunque un commento descrivendo in dettaglio ciò che hai provato a fare. Sapere dove un problema non esiste è importante quasi quanto sapere dove esiste, perché aiuta a restringere il campo delle possibili cause. Se hai qualche teoria sul perché non riesci a riprodurre il problema, ad esempio se pensi che si tratti di un errore di utilizzo o che il problema sia stato risolto da un recente aggiornamento del sistema operativo, includi questa ipotesi nel tuo commento.

Infine, si possono fornire eventuali raccomandazioni al team centrale. Se ritenete che la segnalazione originale sia errata, suggerite di chiudere il problema; se avete una teoria sulla causa del problema, potete suggerire anche quella. I vostri commenti aiuteranno il team centrale a capire come far passare il problema alla fase successiva.

**Se la risoluzione del problema richiede la modifica del codice

Scrivere, eseguire e testare il codice

Per correggere un bug o implementare una funzionalità dovrai scrivere del codice nuovo.

Abbiamo una guida allo stile del codice che illustra le nostre linee guida per la scrittura del codice per BeeWare.

Sviluppo guidato dai test¶

Un buon modo per assicurarsi che il codice funzioni come previsto è quello di scrivere innanzitutto un caso di test per verificarlo. Inizialmente questo caso di test dovrebbe fallire, poiché il codice che sta verificando non è ancora presente. A quel punto è possibile apportare le modifiche necessarie affinché il test abbia esito positivo, con la certezza che ciò che è stato scritto risolva effettivamente il problema previsto.

Esegui il tuo codice¶

Una volta scritto il codice, devi assicurarti che funzioni. Dovrai eseguire manualmente il codice per verificare che faccia ciò che ti aspetti. Se non l'hai già fatto, ti consigliamo di scrivere un caso di test per le modifiche apportate; come accennato in precedenza, questo test dovrebbe fallire se il codice è commentato o non è presente.

Aggiungi il tuo caso di test alla suite di test, in modo che possa essere eseguito insieme agli altri test. Il passo successivo consiste nell'eseguire la suite di test.

Esecuzione dei test e della copertura¶

BeeWare utilizza tox per gestire il processo di test e pytest per la propria suite di test.

Il comando predefinito tox prevede l'esecuzione di:

hook pre-commit
towncrier Verifica delle note di rilascio
controllo della documentazione
suite di test per le versioni disponibili di Python
reportistica sulla copertura del codice

Questo è sostanzialmente ciò che viene eseguito da CI quando si invia una pull request.

Per eseguire l'intera suite di test, digitare:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

L'esecuzione della suite di test completa può richiedere un po' di tempo. È possibile accelerarla notevolmente eseguendo tox in parallelo, ovvero tox p (o tox run-parallel). Quando si esegue la suite di test in parallelo, si riceveranno meno aggiornamenti sullo stato di avanzamento durante l'esecuzione, ma alla fine della sessione di test si otterrà comunque un riepilogo di eventuali problemi rilevati. Dovresti ricevere un messaggio che indica che i test sono stati eseguiti. Potresti vedere SKIPPED test, ma non dovresti mai ottenere risultati di test FAIL o ERROR. Eseguiamo la nostra suite di test completa prima di unire ogni patch. Se tale processo rileva dei problemi, non uniamo la patch. Se trovi un errore o un fallimento nel test, o c'è qualcosa di strano nel tuo ambiente di test, oppure hai trovato un caso limite che non abbiamo mai visto prima: in entrambi i casi, faccelo sapere!

Oltre al superamento dei test, questo dovrebbe indicare una copertura dei test del 100%.

Esecuzione delle varianti di test¶

Eseguire i test su più versioni di Python¶

Per impostazione predefinita, molti dei comandi tox tenteranno di eseguire la suite di test più volte, una volta per ciascuna versione di Python supportata da BeeWare. Per farlo, tuttavia, ciascuna versione di Python deve essere installata sul tuo computer ed essere disponibile per il processo di [rilevamento]tox di Python da parte di (https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery). In generale, se una versione di Python è disponibile tramite PATH, allora tox dovrebbe essere in grado di individuarla e utilizzarla.

Esegui solo la suite di test¶

Se stai sviluppando rapidamente una nuova funzionalità, non è necessario eseguire l'intera suite di test; puoi eseguire solo i test unitari. Per farlo, esegui:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

Eseguire un sottoinsieme di test¶

Per impostazione predefinita, tox esegue tutti i test della suite di test unitari. Quando si sviluppa un nuovo test, può essere utile eseguire solo quel test specifico. Per farlo, è possibile passare qualsiasi specificatore pytest come argomento a tox. Questi percorsi dei test sono relativi alla directory briefcase. Ad esempio, per eseguire solo i test contenuti in un singolo file, digitare:

macOSLinuxWindows

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

Anche se esegui solo una parte della suite di test, riceverai comunque un rapporto sulla copertura; tuttavia, i risultati della copertura riporteranno solo le righe di codice eseguite dai test specifici che hai eseguito.

Esegui la suite di test per una versione specifica di Python¶

Per impostazione predefinita, tox -e py verrà eseguito utilizzando l'interprete che il sistema riconosce come python sul tuo computer. Se hai installato più versioni di Python e desideri testare una versione specifica tra quelle installate, puoi specificare la versione di Python da utilizzare. Ad esempio, per eseguire la suite di test su Python 3.10, digita:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

È possibile eseguire un insieme parziale di test aggiungendo -- e una specifica di test alla riga di comando.

Esegui la suite di test senza copertura (veloce)¶

Per impostazione predefinita, tox esegue la suite di test pytest in modalità a thread singolo. È possibile velocizzare l'esecuzione della suite di test eseguendola in parallelo. Questa modalità non genera file di copertura a causa delle difficoltà nel rilevare la copertura all'interno dei processi generati. Per eseguire una singola versione di Python in modalità "fast", digitare:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

È possibile eseguire un sottoinsieme di test aggiungendo -- e una specifica di test alla riga di comando; è possibile utilizzare una versione specifica di Python aggiungendo la versione al target di test (ad es., py310-fast per eseguire fast su Python 3.10).

Copertura del codice¶

BeeWare garantisce una copertura del codice del 100% nel proprio codice sorgente. Quando si aggiunge o si modifica del codice nel progetto, è necessario aggiungere del codice di test per garantire la copertura di tutte le modifiche apportate.

Tuttavia, BeeWare è destinato a più piattaforme e a più versioni di Python, pertanto non è possibile verificare la copertura completa su una singola piattaforma e versione di Python. Per ovviare a questo problema, nella sezione tool.coverage.coverage_conditional_plugin.rules di pyproject.toml sono definite diverse regole di copertura condizionali (ad esempio, no-cover-if-is-windows può essere utilizzato per contrassegnare un blocco di codice che non verrà eseguito durante l'esecuzione della suite di test su Windows). Queste regole vengono utilizzate per identificare sezioni di codice coperte solo su particolari piattaforme o versioni di Python.

È importante notare che la generazione dei report di copertura tra diverse versioni di Python può presentare alcune anomalie. Ad esempio, se i file di copertura vengono generati utilizzando una versione di Python ma la generazione dei report avviene su un'altra versione, il report potrebbe includere falsi positivi relativi a rami non eseguiti. Per questo motivo, per la generazione dei report di copertura si dovrebbe sempre utilizzare la versione più vecchia di Python impiegata per generare i file di copertura.

Comprendere i risultati della copertura¶

Alla fine dell'output del test di copertura dovrebbe comparire un rapporto contenente i dati di copertura raccolti:

Nome    Dichiarazioni   Mancato Branch BrPart   Copertura   Mancanti
 ---------------------------------------------------
 TOTALE    7540 0   1040 0  100,0%

Questo ci indica che la suite di test ha eseguito ogni possibile percorso di ramificazione nel codice. Non è una garanzia al 100% dell'assenza di bug, ma significa che stiamo verificando ogni riga di codice del codice sorgente.

Se apporti modifiche al codice, è possibile che si crei una lacuna nella copertura. In tal caso, il rapporto sulla copertura ti indicherà quali righe non vengono eseguite. Ad esempio, supponiamo di aver apportato una modifica a some/interesting_file.py, aggiungendo una nuova logica. Il rapporto sulla copertura potrebbe apparire più o meno così:

Nome Istr.   Errore Ramo BrPart  Copertura   Mancante
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98,1%   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 TOTALE 7540 1   1726 0  99,9%

Questo ci indica che la riga 170, le righe da 302 a 307 e un salto di ramo dalla riga 320 alla riga 335 non vengono eseguiti dalla suite di test. Per ripristinare questa copertura, dovrai aggiungere nuovi test (o modificare un test esistente).

Rapporto sulla copertura per la piattaforma ospitante e la versione di Python¶

È possibile generare un rapporto di copertura per la propria piattaforma e versione di Python. Ad esempio, per eseguire la suite di test e generare un rapporto di copertura su Python 3.10, eseguire:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

Rapporto sulla copertura per la piattaforma ospitante¶

Se tutte le versioni supportate di Python sono disponibili per tox, è possibile ottenere un rapporto sulla copertura per la piattaforma ospitante eseguendo:

macOSLinuxWindows

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

Reportistica sulla copertura in HTML¶

È possibile generare un rapporto di copertura HTML aggiungendo -html a uno qualsiasi dei nomi degli ambienti di copertura tox, ad esempio:

macOSLinuxWindows

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

Non si tratta solo di scrivere test!¶

Sebbene ci assicuriamo di testare tutto il nostro codice, il compito non consiste solo nel mantenere quel livello di test. Parte del lavoro consiste nel verificare il codice man mano che si procede. Si potrebbe scrivere una serie completa di test per un giubbotto di salvataggio di cemento… ma un giubbotto di salvataggio di cemento sarebbe comunque inutile per lo scopo a cui è destinato!

Mentre sviluppi i test, dovresti verificare che anche il modulo principale sia coerente al suo interno. Se noti nomi di metodi che non sono internamente coerenti (ad esempio, qualcosa chiamato on_select in un modulo, ma chiamato on_selected in un altro), o casi in cui i dati non vengono gestiti in modo coerente, segnalacelo aprendo un ticket. Oppure, se sei sicuro di sapere cosa bisogna fare, crea una pull request che risolva il problema che hai trovato.

**Se la risoluzione del problema richiede la modifica della documentazione

Documentazione di compilazione

Prima di apportare qualsiasi modifica alla documentazione di {{ nome_formale }}, è utile confermare che si può costruire la documentazione esistente.

È necessario avere un interprete Python 3.13 installato e disponibile sul proprio percorso (cioè, python3.13 deve avviare un interprete Python 3.13).

{{ nome_formale }} usa tox per costruire la documentazione. I seguenti comandi di tox devono essere eseguiti dalla stessa posizione del file tox.ini, che si trova nella directory principale del progetto.

Anteprima della documentazione in tempo reale¶

Per favorire la modifica rapida della documentazione, {{ nome_formale }} dispone di una modalità di "anteprima dal vivo".

L'anteprima live verrà generata con avvisi!

Il servizio live è disponibile per iterare gli aggiornamenti della documentazione. Mentre si aggiornano le cose, si può introdurre un problema di markup. I problemi considerati un `AVVERTIMENTO' causano il fallimento della compilazione standard; tuttavia, il servizio live è impostato per indicare gli avvertimenti nell'output della console, pur continuando la compilazione. Questo permette di iterare senza dover riavviare l'anteprima live.

Un AVVISO' è diverso da unERRORE'. Se si introduce un problema considerato un ERRORE, il servizio live fallirà e richiederà un riavvio. Non si riavvierà fino a quando il problema WARNING non sarà risolto.

Per avviare il server live:

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

Questo costruisce la documentazione, avvia un server web per servire la documentazione e controlla il file system per qualsiasi modifica alla fonte della documentazione.

Una volta avviato il server, nell'output della console si vedrà qualcosa di simile a quanto segue:

INFO    -  [11:18:51] In esecuzione su http://127.0.0.1:8000/

Aprire un browser e navigare all'URL fornito. Ora si può iniziare a iterare sulla documentazione. Se viene rilevata una modifica, la documentazione viene ricostruita e qualsiasi browser che visualizza la pagina modificata viene automaticamente aggiornato.

docs-live è un passo iniziale

L'esecuzione di docs-live per lavorare con il server live è pensata per l'iterazione iniziale. Si dovrebbe sempre eseguire una build locale prima di inviare una richiesta di pull.

Costruzione locale¶

Una volta terminata l'iterazione, è necessario eseguire una compilazione locale della documentazione. Questo processo di creazione è progettato per fallire se ci sono problemi di markup. In questo modo è possibile individuare tutto ciò che potrebbe essere sfuggito con il server live.

Generazione di una build locale¶

Per generare una build locale:

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

L'output di questa compilazione sarà nella cartella _build nella radice del progetto.

Generazione di una build locale tradotta¶

La documentazione di BeeWare è tradotta in più lingue. Gli aggiornamenti della documentazione in inglese possono potenzialmente causare problemi nelle build delle altre lingue. È importante verificare che tutte le build funzionino prima di inviare una richiesta di pull.

Per generare una build di tutte le traduzioni disponibili:

macOSLinuxWindows

(verbo) $ tox -e docs-all

(verbo) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

L'output di ogni compilazione di una lingua si trova nella directory associata _build/html/<languagecode>, dove <languagecode> è il codice di due o cinque caratteri associato alla lingua specifica (ad esempio, fr per il francese, it per l'italiano, ecc.)

Se si riscontra un problema con una singola compilazione, è possibile eseguire quella singola compilazione separatamente eseguendo tox -e docs-<languagecode>. Per esempio, per creare solo la documentazione francese, eseguire:

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

L'output di una compilazione in una sola lingua si trova nella directory _build.

Linting della documentazione¶

Il processo di compilazione identifica i problemi di Markdown, ma {{ nome_formale }} esegue alcuni controlli aggiuntivi per lo stile e la formattazione, noti come "linting". Per eseguire i controlli di lint:

macOSLinuxWindows

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

In questo modo si convalida che la documentazione non contiene:

collegamenti ipertestuali morti
parole sbagliate

Se un'ortografia valida di una parola viene identificata come errata, aggiungere la parola all'elenco in docs/spelling_wordlist. Questo aggiungerà la parola al dizionario del correttore ortografico. Quando si aggiunge a questo elenco, ricordate:

Preferiamo l'ortografia statunitense, con alcune libertà per i colloqui specifici della programmazione (ad esempio, "apps") e per i verbi dei nomi (ad esempio, "scrollable").
Qualsiasi riferimento al nome di un prodotto deve utilizzare la capitalizzazione preferita dal prodotto stesso. (ad esempio, "macOS", "GTK", "pytest", "Pygame", "PyScript").
Se un termine viene usato "come codice", allora dovrebbe essere citato come letterale (come questo) invece di essere aggiunto al dizionario.

Scrivere la documentazione

Questi sono i passi da seguire per scrivere il contributo alla documentazione di {{ nome_formale }}.

Aggiornamento della documentazione esistente¶

Se si sta modificando la documentazione esistente, è necessario individuare il file nella cartella /docs/en. La struttura del file segue quella della pagina, quindi è possibile individuare il file utilizzando l'URL della documentazione.

Aggiunta di nuova documentazione¶

Se si sta aggiungendo un nuovo documento, ci sono alcuni passaggi in più.

È necessario creare il documento nella posizione appropriata all'interno della cartella docs/en. A titolo di esempio, diciamo che stiamo aggiungendo un nuovo documento con il nome di file new_doc.md.

Quindi, è necessario aggiornare il file docs/en/SUMMARY.md per includere il nuovo file. Il file SUMMARY.md è organizzato in modo da riflettere la struttura della cartella docs/en, ma soprattutto determina direttamente la struttura della barra laterale sinistra. Se si individua la sezione in cui si intende includere new_doc.md, non è necessario modificare nulla in SUMMARY.md se si vede un percorso jolly. Ad esempio:

- ./percorso/della/directory/*

Se la sezione in cui si intende includere new_doc.md è un elenco di singoli collegamenti a Markdown, è necessario aggiungere un collegamento esplicito al proprio. Per esempio:

- [Il mio nuovo documento](new_doc.md)

Scrivere la documentazione¶

A questo punto è possibile aprire il file desiderato nel proprio editor e iniziare a scrivere.

Abbiamo una guida allo stile della documentazione che delinea le nostre linee guida per la scrittura della documentazione di BeeWare.

**Quando si è pronti a inviare il proprio contributo

Aggiungi una nota di modifica

Molti strumenti di BeeWare usano towncrier per aiutare a costruire le note di rilascio per ogni release. Quando si invia una richiesta di pull a uno degli strumenti applicabili, questa dovrà includere una nota di modifica; questa nota di modifica diventerà la voce nelle note di rilascio che descriverà la modifica apportata.

Ogni richiesta di pull deve includere almeno un file nella cartella changes/ che fornisca una breve descrizione della modifica implementata dalla richiesta di pull. La nota di modifica deve essere in formato Markdown, in un file dal nome <id>.<tipo di frammento>.md. Se la modifica proposta risolve un bug o implementa una funzionalità per la quale esiste un numero di problema esistente, l'ID sarà il numero di quel ticket. Se la modifica non ha un problema corrispondente, il numero di PR può essere usato come ID. Non si conosce il numero di PR finché non si invia la richiesta di pull, quindi il primo passaggio di CI non supererà il controllo towncrier; aggiungendo la nota di modifica e inviando un aggiornamento della PR, il CI dovrebbe passare.

Esistono cinque tipi di frammenti:

caratteristica: La PR aggiunge un nuovo comportamento o una capacità che non era possibile in precedenza (ad esempio, l'aggiunta del supporto per un nuovo formato di pacchettizzazione o una nuova funzionalità in un formato di pacchettizzazione esistente);
bugfix: La PR corregge un bug nell'implementazione esistente;
doc: Il PR rappresenta un miglioramento significativo della documentazione;
La PR rappresenta una modifica incompatibile con le versioni precedenti dell'API {{ nome_formale }}. API; oppure
misc; Una modifica minore o amministrativa (ad esempio, la correzione di un errore di battitura, un chiarimento linguistico minore o l'aggiornamento della versione di una dipendenza) che non deve essere annunciata nelle note di rilascio.

Questa descrizione nella nota di modifica dovrebbe essere un riassunto di alto livello "marketing" della modifica dal punto di vista dell'utente, non una descrizione tecnica approfondita o un dettaglio di implementazione. Si distingue da un messaggio di commit: un messaggio di commit descrive ciò che è stato fatto in modo che i futuri sviluppatori possano seguire il ragionamento per una modifica; la nota di modifica è una descrizione a beneficio degli utenti, che potrebbero non avere conoscenze interne.

Ad esempio, se si risolve un bug relativo alla denominazione del progetto, il messaggio di commit potrebbe essere il seguente:

Applicare un controllo di espressione regolare più forte per escludere i nomi di progetto che iniziano con cifre.

La nota di modifica corrispondente sarebbe qualcosa di simile:

I nomi dei progetti non possono più iniziare con un numero.

Alcune PR introducono più funzionalità e correggono più bug, oppure introducono più modifiche incompatibili con il passato. In questo caso, la PR può avere più file di note di modifica. Se è necessario associare due tipi di frammenti allo stesso ID, è possibile aggiungere un suffisso numerico. Ad esempio, se la PR 789 ha aggiunto una funzionalità descritta dal ticket 123, ha chiuso un bug descritto dal ticket 234 e ha apportato due modifiche incompatibili, si potrebbero avere 4 file di note di modifica:

123.feature.md
234.bugfix.md
789.removal.1.md
789.removal.2.md

Per maggiori informazioni su towncrier e sui tipi di frammenti, vedere News Fragments. È anche possibile vedere esempi esistenti di frammenti di notizie nella cartella changes del repository {{ nome_formale }}. Se questa cartella è vuota, è probabile che sia perché {{ nome_formale }} ha recentemente pubblicato un nuovo rilascio; i file delle note di modifica vengono cancellati e combinati per aggiornare le note di rilascio a ogni rilascio. Si può guardare a quel file per vedere lo stile di commento richiesto; si può guardare a recent merged PRs per vedere come formattare le note di modifica.

Invia una richiesta pull

Dopo aver effettuato il commit di tutte le modifiche, si è pronti a inviare una richiesta di pull. Per garantire un processo di revisione senza intoppi, ci sono alcuni passi da fare.

Lavorare con il pre-commit¶

Quando si esegue il commit di una modifica, il pre-commit viene eseguito automaticamente. Se vengono riscontrati problemi con il commit, questo causerà l'insuccesso del commit. Dove possibile, pre-commit apporterà le modifiche necessarie per correggere i problemi riscontrati. Nell'esempio seguente, il controllo ruff ha rilevato un problema di formattazione del codice:

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

In questo caso, ruff ha risolto automaticamente il problema; è quindi possibile reinserire tutti i file che sono stati modificati come risultato dei controlli pre-commit e reinserire la modifica. Tuttavia, alcuni controlli richiedono modifiche manuali. Una volta apportate le modifiche, si possono aggiungere nuovamente i file modificati e rifare il commit.

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

Una volta che tutto è stato superato, si vedrà un messaggio che indica che il commit è stato finalizzato e il log di git mostrerà il commit come l'aggiunta più recente. Ora si è pronti a fare il push su GitHub.

Spingere le modifiche su GitHub e creare la richiesta di pull.¶

La prima volta che si effettua un push su GitHub, viene fornito un URL che porta direttamente alla pagina di GitHub per creare una nuova richiesta di pull. Seguire l'URL e creare la richiesta di pull.

Di seguito viene mostrato un esempio di cosa aspettarsi da push, con l'URL evidenziato.

macOSLinuxWindows

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

Se avete precedentemente spinto il ramo corrente su GitHub, non riceverete più l'URL. Tuttavia, ci sono altri modi per raggiungere l'URL di creazione della PR:

Navigare nel repository upstream, cliccare su "Pull Requests" e poi su "New pull request" e scegliere il repository da cui si vuole inviare la richiesta di pull.
Se si è effettuato un push di recente, navigare nel repository upstream, individuare il banner sopra l'elenco dei file che indica che il repository ha "avuto push recenti" e fare clic sul pulsante "Compare & pull request".
Utilizzare il comando gh pr create di GitHub CLI e compilare le richieste.
Usare il comando GitHub CLI gh pr create --web per aprire un browser web alla pagina di creazione della PR.

Ognuna di queste opzioni consente di creare una nuova richiesta di pull.

La CLI GitHub: gh

GitHub fornisce la GitHub CLI, che consente di accedere a molte delle funzionalità di GitHub dal proprio terminale, attraverso il comando gh. La Documentazione della GitHub CLI copre tutte le funzionalità.

Contenuto della richiesta di pull¶

Il titolo di una richiesta di pull deve essere informativo, chiaro e conciso. Cercate di mantenerlo breve se possibile, ma titoli più lunghi sono accettabili, se necessario. Un buon titolo di una PR dovrebbe dare a una persona senza alcun contesto un'idea ragionevolmente solida di quale sia il bug o la funzionalità implementata dalla PR.

La descrizione della PR deve riflettere chiaramente le modifiche apportate. Una persona priva di contesto dovrebbe essere in grado di leggere la descrizione e comprendere in modo relativamente completo il motivo della modifica. Evitate battute, espressioni idiomatiche, colloquialismi e formattazioni inutili, come l'uso di tutte le maiuscole o di una punteggiatura eccessiva; si tratta di una spiegazione diretta di ciò che sta accadendo nella vostra RP, ed evitare questi elementi rende la descrizione più accessibile agli altri.

Se ci sono casi di riproduzione o regimi di test utilizzati che non fanno già parte delle modifiche presenti nella PR, devono essere spiegati e inclusi nella PR. La spiegazione dovrebbe includere come eseguirli e cosa fare per riprodurre il risultato desiderato.

Se la richiesta di pull risolve il problema #1234, si dovrebbe includere il testo Fixes #1234 nella descrizione della richiesta di pull. Questo farà sì che il problema venga automaticamente chiuso quando la richiesta di pull viene unita. È possibile fare riferimento ad altre discussioni, problemi o richieste di pull usando la stessa sintassi #1234. È possibile fare riferimento a un problema su un repository diverso anteponendo il numero - per esempio python/cpython#1234 si riferisce al problema 1234 sul repository CPython.

Integrazione continua¶

L'integrazione continua, o CI, è il processo di esecuzione di controlli automatici sulla richiesta di pull. Questo può includere controlli semplici, come la verifica che il codice sia formattato correttamente, ma anche l'esecuzione della suite di test e la creazione della documentazione.

Le modifiche che possono causare un fallimento del CI sono molteplici. In linea di massima, non revisioneremo una PR che non passa il CI. Se si crea una richiesta di pull e il CI fallisce, non inizieremo la revisione finché non passerà. Se le vostre modifiche causano un fallimento, è vostra responsabilità indagare sul motivo e risolvere il problema.

Quando il CI fallisce, i link di fallimento vengono visualizzati in fondo alla pagina PR, sotto il titolo "Alcuni controlli non hanno avuto successo". Verrà visualizzato un elenco di controlli falliti, che apparirà in cima all'elenco di tutti i controlli se ci sono anche controlli superati. Se si fa clic sul link relativo al fallimento, si accede al registro. Il log spesso fornisce tutte le informazioni necessarie per capire cosa ha causato il fallimento. Leggete il registro e cercate di capire perché si è verificato il guasto, quindi fate il necessario per risolverlo.

Occasionalmente, un controllo CI fallisce per motivi non correlati alle modifiche apportate. Ciò potrebbe essere dovuto a un problema sulla macchina che esegue il controllo CI o perché un controllo CI è instabile. Se si verifica un errore e si è abbastanza certi che non sia correlato alle modifiche, aggiungere un commento alla PR e lo esamineremo.

Per attivare un nuovo ciclo CI, è necessario apportare nuove modifiche al ramo.

Se vi trovate in una situazione in cui avete bisogno di aiuto per far passare l'IC, lasciate un commento sulla PR e fateci sapere che faremo il possibile per aiutarvi.

I controlli pre-commit e `towncrier

Se uno dei due controlli pre-commit o towncrier fallisce, la maggior parte degli altri controlli del CI saranno bloccati. È necessario risolvere i problemi applicabili prima che l'intero set di controlli venga eseguito.

Le risorse del CI sono limitate. È importante capire che ogni volta che si esegue il push sul ramo, si avvia il CI. Se si devono apportare diverse modifiche, è meglio farle localmente e spingerle tutte in una volta. CI verrà eseguito solo sul commit più recente in un batch, riducendo al minimo il carico sul nostro sistema CI.

Il processo di invio della PR non è concluso finché non passa il CI, o non si può fornire una spiegazione del perché non lo sia.