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:

$ python3 --version

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:

$ python3 --version

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/<your username>/beeware.git

(sostituendo il proprio nome utente GitHub)

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

$ git clone https://github.com/<your username>/beeware.git

(sostituendo il proprio nome utente GitHub)

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

C:\...>git clone https://github.com/<your username>/beeware.git

(sostituendo il proprio nome utente GitHub)

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

Fixing a bug or implementing a feature will require you to write some new code.

We have a code style guide that outlines our guidelines for writing code for BeeWare.

Test-driven development¶

A good way to ensure your code is going to do what you expect it to, is to first write a test case to test for it. This test case should fail initially, as the code it is testing for is not yet present. You can then write the code changes needed to make the test pass, and know that what you've written is solving the problem you are expecting it to.

Run your code¶

Once your code is written, you need to ensure it runs. You'll need to manually run your code to verify it is doing what you expect. If you haven't already, you'll want to write a test case for your changes; as mentioned above, this test should fail if your code is commented out or not present.

You'll add your test case to the test suite, so it can be run alongside the other tests. The next step is to run the test suite.

Running tests and coverage¶

BeeWare uses tox to manage the testing process and pytest for its own test suite.

The default tox command includes running:

pre-commit hooks
towncrier release note check
documentation linting
test suite for available Python versions
code coverage reporting

This is essentially what is run by CI when you submit a pull request.

To run the full test suite, run:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

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

The full test suite can take a while to run. You can speed it up considerably by running tox in parallel, by running tox p (or tox run-parallel). When you run the test suite in parallel, you'll get less feedback on the progress of the test suite as it runs, but you'll still get a summary of any problems found at the end of the test run. You should get some output indicating that tests have been run. You may see SKIPPED tests, but shouldn't ever get any FAIL or ERROR test results. We run our full test suite before merging every patch. If that process discovers any problems, we don't merge the patch. If you do find a test error or failure, either there's something odd in your test environment, or you've found an edge case that we haven't seen before - either way, let us know!

In addition to the tests passing, this should report 100% test coverage.

Running test variations¶

Run tests for multiple versions of Python¶

By default, many of the tox commands will attempt to run the test suite multiple times, once for each Python version supported by BeeWare. To do this, though, each of the Python versions must be installed on your machine and available to tox's Python discovery process. In general, if a version of Python is available via PATH, then tox should be able to find and use it.

Run only the test suite¶

If you're rapidly iterating on a new feature, you don't need to run the full test suite; you can run only the unit tests. To do this, run:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Run a subset of tests¶

By default, tox will run all tests in the unit test suite. When you're developing your new test, it may be helpful to run just that one test. To do this, you can pass in any pytest specifier as an argument to tox. These test paths are relative to the briefcase directory. For example, to run only the tests in a single file, run:

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

You'll still get a coverage report when running a part of the test suite - but the coverage results will only report the lines of code that were executed by the specific tests you ran.

Run the test suite for a specific Python version¶

By default tox -e py will run using whatever interpreter resolves as python on your machine. If you have multiple Python versions installed, and want to test a specific Python version from the versions you have installed, you can specify a specific Python version to use. For example, to run the test suite on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

A subset of tests can be run by adding -- and a test specification to the command line.

Run the test suite without coverage (fast)¶

By default, tox will run the pytest suite in single threaded mode. You can speed up the execution of the test suite by running the test suite in parallel. This mode does not produce coverage files due to complexities in capturing coverage within spawned processes. To run a single python version in "fast" mode, run:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

A subset of tests can be run by adding -- and a test specification to the command line; a specific Python version can be used by adding the version to the test target (e.g., py310-fast to run fast on Python 3.10).

Code coverage¶

BeeWare maintains 100% branch coverage in its codebase. When you add or modify code in the project, you must add test code to ensure coverage of any changes you make.

However, BeeWare targets multiple platforms, as well as multiple versions of Python, so full coverage cannot be verified on a single platform and Python version. To accommodate this, several conditional coverage rules are defined in the tool.coverage.coverage_conditional_plugin.rules section of pyproject.toml (e.g., no-cover-if-is-windows can be used to flag a block of code that won't be executed when running the test suite on Windows). These rules are used to identify sections of code that are only covered on particular platforms or Python versions.

Of note, coverage reporting across Python versions can be a bit quirky. For instance, if coverage files are produced using one version of Python but coverage reporting is done on another, the report may include false positives for missed branches. Because of this, coverage reporting should always use the oldest version Python used to produce the coverage files.

Understanding coverage results¶

At the end of the coverage test output there should be a report of the coverage data that was gathered:

Name    Stmts   Miss Branch BrPart   Cover   Missing
----------------------------------------------------
TOTALE 7540 0 1040 0 100,0% 0

This tells us that the test suite has executed every possible branching path in the code. This isn't a 100% guarantee that there are no bugs, but it does mean that we're exercising every line of code in the codebase.

If you make changes to the codebase, it's possible you'll introduce a gap in this coverage. When this happens, the coverage report will tell you which lines aren't being executed. For example, lets say we made a change to some/interesting_file.py, adding some new logic. The coverage report might look something like:

Nome Stmts Miss Branch BrPart Cover Missing
--------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98,1% 170, 302-307, 320->335
--------------------------------------------------------------------------------
TOTALE 7540 1 1726 0 99,9

This tells us that line 170, lines 302-307, and a branch jumping from line 320 to line 335, are not being executed by the test suite. You'll need to add new tests (or modify an existing test) to restore this coverage.

Coverage report for host platform and Python version¶

You can generate a coverage report for your platform and version of Python. For example, to run the test suite and generate a coverage report on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Coverage report for host platform¶

If all supported versions of Python are available to tox, then coverage for the host platform can be reported by running:

macOSLinuxWindows

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

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

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

Coverage reporting in HTML¶

A HTML coverage report can be generated by appending -html to any of the coverage tox environment names, for instance:

macOSLinuxWindows

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

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

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

It's not just about writing tests!¶

Although we ensure that we test all of our code, the task isn't just about maintaining that level of testing. Part of the task is to audit the code as you go. You could write a comprehensive set of tests for a concrete life jacket… but a concrete life jacket would still be useless for the purpose it was intended!

As you develop tests, you should be checking that the core module is internally consistent as well. If you notice any method names that aren't internally consistent (e.g., something called on_select in one module, but called on_selected in another), or where the data isn't being handled consistently, flag it and bring it to our attention by raising a ticket. Or, if you're confident that you know what needs to be done, create a pull request that fixes the problem you've found.

///

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

/// details-abstract | 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".

/// warning | 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 un `ERRORE'. 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:



/// tab | macOS



```console
(venv) $ tox -e docs-live

LinuxWindows

(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] Serving on 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

(venv) $ tox -e docs-all

(venv) $ 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:

- ./path/to/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:

- [My new document](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.