Linee guida per la richiesta di pull #

Le richieste pull (PR) sono il meccanismo per contribuire al codice e alla documentazione di Matplotlibs.

Riepilogo per autori di richieste pull #

Nota

  • Apprezziamo i contributi di persone con tutti i livelli di esperienza. In particolare se questa è la tua prima PR non deve essere tutto perfetto. Ti guideremo attraverso il processo di PR.

  • Tuttavia, prova a seguire le linee guida di seguito nel miglior modo possibile per contribuire a rendere il processo di PR rapido e agevole.

  • Sii paziente con i revisori. Facciamo del nostro meglio per rispondere rapidamente, ma abbiamo una larghezza di banda limitata. Se non ricevi feedback entro un paio di giorni, inviaci un messaggio inviando un commento al tuo PR.

Quando fai un PR, presta attenzione a:

  • Scegli come target il ramo principale .

  • Rispettare le linee guida sulla codifica .

  • Aggiornare la documentazione se necessario.

  • Cerca di rendere il PR il più "pronto all'uso" possibile. Questo aiuta ad accelerare il processo di revisione.

  • È consentito aprire PR incomplete o in corso di elaborazione se hai bisogno di aiuto o feedback dagli sviluppatori. Puoi contrassegnarle come richieste pull in bozza su GitHub.

  • Quando aggiorni il tuo PR, invece di aggiungere nuovi commit per sistemare qualcosa, considera di modificare i tuoi commit iniziali per mantenere pulita la cronologia. Puoi ottenere questo risultato utilizzando

    git commit --amend --no-edit
git push [your-remote-repo] [your-branch] --force-with-lease

Vedi anche Contribuire per come fare un PR.

Riepilogo per i revisori delle richieste pull n.

Nota

  • Se disponi dei diritti di commit, sei autorizzato a utilizzarli. Per favore aiutaci a rivedere e unire i PR!

  • Sii paziente e gentile con i contributori.

Argomenti contenuti:

Temi organizzativi:

Linee guida dettagliate #

Documentazione n.

  • Ogni nuova funzionalità dovrebbe essere documentata. Se si tratta di un nuovo modulo, non dimenticare di aggiungere un nuovo file rst alla documentazione dell'API.

  • Ogni funzione di plottaggio di alto livello dovrebbe avere un piccolo esempio nella Examplessezione della docstring. Questo dovrebbe essere il più semplice possibile per dimostrare il metodo. Esempi più complessi dovrebbero essere inseriti in un file di esempio dedicato nella examplesdirectory, che verrà visualizzato nella galleria di esempi nella documentazione.

  • Crea i documenti e assicurati che tutti gli avvisi di formattazione vengano affrontati.

  • Vedi Scrittura della documentazione per la nostra guida allo stile della documentazione.

  • Se la tua modifica è una nuova funzionalità importante, aggiungi una voce a doc/users/whats_new.rst.

  • Se modifichi l'API in modo non compatibile con le versioni precedenti, documentalo aggiungendo un file nella relativa sottodirectory di doc/api/next_api_changes/, probabilmente nella behavior/ sottodirectory.

Etichette #

  • Se disponi dei diritti per impostare le etichette, contrassegna il PR con etichette descrittive. Consulta l' elenco delle etichette .

  • Se il PR apporta modifiche all'azione di costruzione della ruota, aggiungi l'etichetta "Esegui cibuildwheel" per abilitare il test delle ruote.

Pietre miliari #

  • Imposta la pietra miliare secondo queste regole:

    • Le nuove funzionalità e le modifiche all'API sono fondamentali per la prossima versione minore v3.X.0.

    • Le correzioni di bug e le modifiche alla docstring sono fondamentali per la prossima versione della patchv3.X.Y

    • Le modifiche alla documentazione (tutti i file .rst e gli esempi) sono cardine v3.X-doc

    Se si applicano più regole, scegli la prima corrispondenza dall'elenco precedente.

    L'impostazione di una pietra miliare non implica né garantisce che una PR verrà unita per quella versione, ma se dovesse essere unita in quale versione si troverebbe.

    Tutti questi PR dovrebbero mirare al ramo principale. Il tag milestone attiva un backport automatico per le pietre miliari che hanno un ramo corrispondente.

Unione #

  • La documentazione e gli esempi possono essere uniti dal primo revisore. Usa la soglia "è meglio di prima?" come criteri di revisione.

  • Per le modifiche al codice (qualsiasi cosa in srco lib) almeno due sviluppatori principali (quelli con diritti di commit) dovrebbero esaminare tutte le richieste pull. Se sei il primo a rivedere un PR e ad approvare le modifiche, utilizza lo strumento "approva review" di GitHub per contrassegnarlo come tale. Se sei un revisore successivo, approva la recensione e se ritieni che non sia necessaria un'altra revisione, unisci il PR.

    Assicurati che tutte le modifiche all'API siano documentate in un file in una delle sottodirectory di doc/api/next_api_changese che le nuove funzionalità significative abbiano una voce in doc/user/whats_new.

    • Se un PR ha già una recensione positiva, uno sviluppatore principale (ad esempio il primo revisore, ma non necessariamente) può sostenere tale PR per la fusione. Per fare ciò, dovrebbero eseguire il ping di tutti gli sviluppatori principali sia su GitHub che sulla mailing list degli sviluppatori ed etichettare il PR con "Unisci con revisione singola?" etichetta. Altri sviluppatori principali possono quindi rivedere il PR e unirlo o rifiutarlo, o semplicemente richiedere che riceva una seconda revisione prima di essere unito. Se nessuno richiede tale seconda revisione entro una settimana, il PR può essere unito sulla base di tale singola revisione.

      Uno sviluppatore principale dovrebbe sostenere solo una PR alla volta e dovremmo cercare di mantenere ragionevole il flusso delle PR sostenute.

  • Non eseguire l'unione automatica, ad eccezione delle "piccole" patch per annullare l'interruzione dell'elemento della configurazione o quando un altro revisore lo consente esplicitamente (ad esempio, "Approva il passaggio dell'elemento della configurazione, può unire automaticamente quando è verde").

Test automatizzati #

Ogni volta che viene creata o aggiornata una richiesta pull, vari strumenti di test automatici verranno eseguiti su tutte le piattaforme e versioni di Python supportate.

  • Assicurati che le pipeline Linting, GitHub Actions, AppVeyor, CircleCI e Azure passino prima dell'unione (tutti i controlli sono elencati nella parte inferiore della pagina GitHub della tua richiesta pull). Ecco alcuni suggerimenti per trovare la causa del fallimento del test:

    • Se Linting fallisce, hai un problema di stile del codice, che verrà elencato come annotazioni sul diff della richiesta pull.

    • Se un'esecuzione di GitHub Actions o AppVeyor non riesce, cerca nel log FAILURES. La sezione successiva conterrà informazioni sui test falliti.

    • Se CircleCI fallisce, probabilmente hai qualche problema di stile reStructuredText nei documenti. Cerca nel registro CircleCI WARNING.

    • Se le pipeline di Azure hanno esito negativo con un errore di confronto delle immagini, puoi trovare le immagini come artefatti del processo di Azure:

      • Fai clic su Dettagli sul segno di spunta nella pagina PR di GitHub.

      • Fare clic su Visualizza altri dettagli su Azure Pipelines per passare ad Azure.

      • Nella pagina di panoramica gli artefatti sono elencati nella sezione Correlati .

  • Codecov e LGTM sono attualmente solo a scopo informativo. Il loro fallimento non è necessariamente un ostacolo.

  • tox non viene utilizzato nei test automatizzati. È supportato per i test in locale.

  • Se sai che le tue modifiche non hanno bisogno di essere testate (questo è molto raro!), tutti i CI possono essere saltati per un dato commit includendo o nel messaggio di commit. Se sai che è necessario eseguire solo un sottoinsieme di elementi della configurazione (ad esempio, se stai modificando un blocco di semplice reStructuredText e desideri che venga eseguito solo CircleCI per eseguire il rendering del risultato), i singoli elementi della configurazione possono essere saltati anche sui singoli commit utilizzando quanto segue sottostringhe nei messaggi di commit:[ci skip][skip ci]

    • Azioni GitHub:[skip actions]

    • AppVeyor: (deve essere nella prima riga del commit)[skip appveyor]

    • Pipeline di Azure:[skip azp]

    • CerchioCI:[skip circle]

Numero di commit e schiacciamenti #

  • Lo schiacciamento è caso per caso. L'equilibrio è tra l'onere per il contributore, il mantenimento di una cronologia relativamente pulita e il mantenimento di una cronologia utilizzabile per la divisione in due. L'unica volta in cui siamo veramente severi al riguardo è eliminare i file binari (ad esempio rigenerazioni multiple di immagini di prova) e rimuovere le unioni a monte.

  • Non lasciare che il perfetto sia nemico del buono, in particolare per la documentazione o PR di esempio. Se ti ritrovi a dare molti piccoli suggerimenti, apri una PR rispetto al ramo originale, invia le modifiche al ramo contributore o unisci la PR e poi apri una nuova PR contro l'upstream.

  • Se invii una filiale di un collaboratore, lascia un commento che spieghi cosa hai fatto, ad esempio "Mi sono preso la libertà di inviare una piccola PR di pulizia alla tua filiale, grazie per il tuo lavoro". Se hai intenzione di apportare modifiche sostanziali al codice o all'intento del PR, verifica prima con il collaboratore.

Filiali e backport #

Filiali attuali #

Gli attuali rami attivi sono

principale

L'attuale versione di sviluppo. Futuri rilasci minori ( v3.N.0 ) saranno ramificati da questo.

v3.Nx

Ramo di manutenzione per Matplotlib 3.N. Le future versioni di patch saranno ramificate da questo.

v3.NM-doc

Documentazione per la versione corrente. In una versione patch, questo verrà sostituito da un ramo con nome appropriato per la nuova versione.

Selezione filiale per richieste pull #

In genere, tutte le richieste pull devono essere indirizzate al ramo principale.

Altri rami sono alimentati tramite automatico o manuale . Mirare direttamente ad altre filiali è solo raramente necessario per lavori di manutenzione straordinaria.

Strategia di backport #

Eseguiremo sempre il backport al ramo di rilascio della patch ( v3.Nx ):

  • correzioni di bug critici (segfault, mancata importazione, cose che l'utente non può aggirare)

  • correzioni per regressioni rispetto alle ultime due versioni.

Tutto il resto (regressioni rispetto a versioni precedenti, bug/incoerenze API che l'utente può aggirare nel proprio codice) sono caso per caso, dovrebbero essere a basso rischio e necessitano di qualcuno che difenda e guidi attraverso il backport.

Le uniche modifiche di cui eseguire il backport nel ramo della documentazione ( v3.NM-doc ) sono le modifiche a doc, exampleso tutorials. Eventuali modifiche libao srcincluse modifiche solo a docstring non dovrebbero essere trasferite a questo ramo.

Backport automatizzati #

Utilizziamo il bot meeseeksdev per eseguire automaticamente il backport delle unioni alla base del ramo di manutenzione corretta sulla pietra miliare. Per funzionare correttamente, la pietra miliare deve essere impostata prima dell'unione. Se disponi dei diritti di commit, il bot può anche essere attivato manualmente dopo un'unione lasciando un messaggio sul PR. In caso di conflitti, meeseekdevs ti informerà che il backport deve essere eseguito manualmente.@meeseeksdev backport to BRANCH

Il ramo di destinazione viene configurato inserendo la descrizione dell'attività cardine sulla propria riga.on-merge: backport to TARGETBRANCH

Se il bot non funziona come previsto, segnala i problemi a Meeseeksdev .

Backport manuali #

Quando si eseguono i backport, copiare il modulo utilizzato da meeseekdev, . Se hai bisogno di risolvere manualmente i conflitti, annotali e come li hai risolti nel messaggio di commit.Backport PR #XXXX: TITLE OF PR

Facciamo un backport da main a v2.2.x assumendo:

  • matplotlibè un ramo remoto di sola lettura del repository matplotlib/matplotlib

È TARGET_SHAl'hash del commit di unione di cui desideri eseguire il backport. Questo può essere letto dalla pagina GitHub PR (nell'interfaccia utente con la notifica di unione) o tramite gli strumenti della CLI git.

Supponendo che tu abbia già un ramo locale v2.2.x(in caso contrario, allora ) e che il tuo puntamento remoto a sia chiamato :git checkout -b v2.2.xhttps://github.com/matplotlib/matplotlibupstream

git fetch upstream
git checkout v2.2.x  # or include -b if you don't already have this.
git reset --hard upstream/v2.2.x
git cherry-pick -m 1 TARGET_SHA
# resolve conflicts and commit if required

I file con conflitti possono essere elencati da e dovranno essere corretti a mano (cercare su ). Una volta risolto il conflitto, dovrai aggiungere nuovamente i file al ramo e quindi continuare il cherry pick:git status>>>>>

git add lib/matplotlib/conflicted_file.py
git add lib/matplotlib/conflicted_file2.py
git cherry-pick --continue

Usa la tua discrezione per spingere direttamente a monte o per aprire un PR; assicurati di spingere o PR contro il v2.2.xramo a monte, non main!