Implementazione di una nuova funzionalità

Una volta concluso il processo di proposta, dovreste avere un progetto completo per una nuova funzionalità. Questo significa che è ora di iniziare a scrivere!

Se la vostra funzione richiede un'implementazione specifica per la piattaforma, il processo di proposta dovrebbe aver convalidato che l'idea potrebbe essere implementata su tutte le piattaforme. Tuttavia, come persona che implementa una nuova funzione per la prima volta, non siete responsabili dell'implementazione della nuova funzione per tutte le piattaforme. È necessario fornire un'implementazione completa per almeno una piattaforma, compresi i test. Per tutte le altre piattaforme, si dovrà fornire un'implementazione "stub", ovvero un'implementazione che fornisca la definizione dell'interfaccia, ma che sollevi un NotImplementedError o invii un messaggio di log che indichi che il comportamento non è implementato su quella piattaforma.

Una parte importante dell'implementazione di una nuova funzionalità è assicurarsi che questa sia completamente documentata. Questo significa, come minimo, garantire la presenza di una documentazione dell'API, ma può anche richiedere l'aggiunta di una guida alle procedure o agli argomenti.

Contribuire a nuove funzionalità

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

Evitare lo scope creep

Lo "Scope creep" si verifica quando l'elenco dei problemi risolti o delle funzionalità implementate da un singolo contributo cresce significativamente al di là di quanto previsto all'inizio del lavoro. Si inizia con un semplice problema; si scopre un problema strettamente correlato e si decide di includere anche quella soluzione; poi una terza… prima di rendersene conto, si ha una richiesta di pull che chiude 5 problemi e aggiunge 3 nuove funzionalità, comprese decine di file.

Lo Scope Creep capita a tutti. È un concetto fin troppo familiare agli sviluppatori esperti; tutti noi l'abbiamo fatto più volte e abbiamo sperimentato tutti i problemi che ne derivano.

Ci sono ragioni molto pratiche per evitare lo scope creep. Più un contributo diventa grande, più è difficile lavorarci. Diventa più difficile identificare i casi limite o i problemi potenziali, il che significa che la qualità complessiva del contributo può diminuire. Anche le revisioni diventano più impegnative quando il revisore deve occuparsi di più contesti, potenzialmente non correlati. Un contributo più grande significa più commenti di revisione e, come collaboratore, può diventare difficile seguire più thread di revisione. Anche l'esperienza su GitHub ne risentirà: l'interfaccia utente di GitHub rallenterà con l'aumentare delle dimensioni di una PR, il che significa che navigare i file attraverso l'interfaccia di GitHub e tentare di lasciare commenti di revisione diventa sempre più difficile.

Ogni volta che trovate un motivo per aggiungere al vostro contributo qualcosa che non fa esplicitamente parte della proposta originale o della segnalazione di un bug, dovete considerare se state andando incontro a un'espansione dell'ambito. Ci sono due caratteristiche distinte che potrebbero essere implementate separatamente? È possibile implementare una funzionalità con una limitazione o un bug noto, e risolvere tale bug in una richiesta di pull successiva? Una parte della correzione di un bug è indipendente da un'altra? Se una parte di un cambiamento può essere esclusa senza alterare il contributo originale, probabilmente dovrebbe esserlo.

Lo sviluppo di software è sempre un processo di miglioramento incrementale. Ogni singolo contributo dovrebbe lasciare la base di codice in uno stato migliore dopo la fusione, ma è del tutto accettabile lasciare bug o parti di funzionalità come lavoro per miglioramenti futuri. Questo può significare suddividere una richiesta di pull in più parti che possono essere riviste in modo indipendente, oppure registrare un problema in modo che qualcun altro possa indagare e risolvere il problema.

Limitare la portata di ogni contributo aiuta tutte le persone coinvolte, voi compresi. I revisori, e anche voi stessi, lo apprezzeranno.

Implementare la nuova funzionalità

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.

///

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

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.