Controlli su una Pull Request

Quando apri una pull request sui 🤗 Transformers, vengono eseguiti un discreto numero di controlli per assicurarsi che la patch che stai aggiungendo non stia rompendo qualcosa di esistente. Questi controlli sono di quattro tipi:

• test regolari
• costruzione della documentazione
• stile del codice e della documentazione
• coerenza generale del repository

In questo documento, cercheremo di spiegare quali sono i vari controlli e le loro ragioni, oltre a spiegare come eseguire il debug locale se uno di essi fallisce sulla tua PR.

Nota che tutti richiedono un’installazione dev:

pip install transformers[dev]

o un’installazione modificabile:

pip install -e .[dev]

all’interno del repo Transformers.

Tests

Tutti i job che iniziano con ci/circleci: run_tests_ eseguono parti della suite di test dei Transformers. Ognuno di questi job si concentra su una parte della libreria in un determinato ambiente: per esempio ci/circleci: run_tests_pipelines_tf esegue il test delle pipeline in un ambiente in cui è installato solo TensorFlow.

Nota che per evitare di eseguire i test quando non ci sono cambiamenti reali nei moduli che si stanno testando, ogni volta viene eseguita solo una parte della suite di test: viene eseguita una utility per determinare le differenze nella libreria tra prima e dopo la PR (ciò che GitHub mostra nella scheda “Files changes”) e sceglie i test che sono stati impattati dalla diff. Questa utility può essere eseguita localmente con:

python utils/tests_fetcher.py

dalla root del repo Transformers. Di seguito ciò che farà:

1. Controlla per ogni file nel diff se le modifiche sono nel codice o solo nei commenti o nelle docstrings. Vengono mantenuti solo i file con modifiche reali al codice.
2. Costruisce una mappa interna che fornisce per ogni file del codice sorgente della libreria tutti i file su cui ha un impatto ricorsivo. Si dice che il modulo A ha un impatto sul modulo B se il modulo B importa il modulo A. Per l’impatto ricorsivo, abbiamo bisogno di una catena di moduli che va dal modulo A al modulo B in cui ogni modulo importa il precedente.
3. Applica questa mappa ai file raccolti nel passaggio 1, si ottiene l’elenco dei file del modello interessati dalla PR.
4. Mappa ciascuno di questi file con i corrispondenti file di test e ottiene l’elenco dei test da eseguire.

Quando esegui lo script in locale, dovresti ottenere la stampa dei risultati dei passi 1, 3 e 4 e quindi sapere quali test sono stati eseguiti. Lo script creerà anche un file chiamato test_list.txt che contiene l’elenco dei test da eseguire e che puoi eseguire localmente con il seguente comando:

python -m pytest -n 8 --dist=loadfile -rA -s $(cat test_list.txt)

Nel caso in cui qualcosa sia sfuggito, l’intera suite di test viene eseguita quotidianamente.

Build della documentazione

Il job ci/circleci: build_doc esegue una build della documentazione per assicurarsi che tutto sia a posto una volta che la PR è stata unita. Se questo passaggio fallisce, puoi controllare localmente entrando nella cartella docs del repo Transformers e digitare

make html

Sphinx non è noto per i suoi messaggi di errore chiari, quindi potrebbe essere necessario che provi alcune cose per trovare davvero la fonte dell’errore.

Stile del codice e della documentazione

La formattazione del codice viene applicata a tutti i file sorgenti, agli esempi e ai test usando black e isort. Abbiamo anche uno strumento personalizzato che si occupa della formattazione delle docstring e dei file rst (utils/style_doc.py), così come dell’ordine dei lazy imports eseguiti nei file __init__.py dei Transformers (utils/custom_init_isort.py). Tutto questo può essere lanciato eseguendo

make style

I controlli della CI sono applicati all’interno del controllo ci/circleci: check_code_quality. Esegue anche flake8, che dà un’occhiata di base al codice e si lamenta se trova una variabile non definita o non utilizzata. Per eseguire questo controllo localmente, usare

make quality

Questa operazione può richiedere molto tempo, quindi per eseguire la stessa operazione solo sui file modificati nel branch corrente, eseguire

make fixup

Quest’ultimo comando eseguirà anche tutti i controlli aggiuntivi per la consistenza del repository. Diamogli un’occhiata.

Coerenza del repository

All’interno sono raggruppati tutti i test per assicurarsi che la tua PR lasci il repository in un buono stato ed è eseguito dal controllo ci/circleci: check_repository_consistency. Puoi eseguire localmente questo controllo eseguendo quanto segue:

make repo-consistency

Questo verifica che:

• Tutti gli oggetti aggiunti all’init sono documentati (eseguito da utils/check_repo.py)
• Tutti i file __init__.py hanno lo stesso contenuto nelle loro due sezioni (eseguito da utils/check_inits.py)
• Tutto il codice identificato come copia da un altro modulo è coerente con l’originale (eseguito da utils/check_copies.py)
• Le traduzioni dei README e l’indice della documentazione hanno lo stesso elenco di modelli del README principale (eseguito da utils/check_copies.py)
• Le tabelle autogenerate nella documentazione sono aggiornate (eseguito da utils/check_table.py)
• La libreria ha tutti gli oggetti disponibili anche se non tutte le dipendenze opzionali sono installate (eseguito da utils/check_dummies.py)

Se questo controllo fallisce, le prime due voci richiedono una correzione manuale, mentre le ultime quattro possono essere corrette automaticamente per te eseguendo il comando

make fix-copies

Ulteriori controlli riguardano le PR che aggiungono nuovi modelli, principalmente che:

• Tutti i modelli aggiunti sono in un Auto-mapping (eseguita da utils/check_repo.py)
• Tutti i modelli sono testati correttamente (eseguito da utils/check_repo.py)