Vai al contenuto

Invio di 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:

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

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

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

La tua richiesta pull potrebbe richiedere contenuti aggiuntivi, come una nota di modifica, prima di poter essere revisionata.