Guida al rilascio n.

Questo documento è rilevante solo per i gestori di rilascio di Matplotlib.

Una guida per gli sviluppatori che stanno realizzando una versione di Matplotlib.

Nota

Ciò presuppone che sia presente un telecomando di sola lettura per il repository canonico remotee un telecomando di lettura/scritturaDANGER

Test n.

Utilizziamo GitHub Actions per l'integrazione continua. Durante la preparazione per una versione, il commit con tag finale deve essere testato localmente prima di essere caricato:

pytest -n 8 .

Inoltre, è necessario eseguire e ispezionare manualmente il seguente test:

python tools/memleak.py agg 1000 agg.pdf

Inoltre, quanto segue dovrebbe essere eseguito e ispezionato manualmente, ma attualmente non funziona:

pushd examples/tests/
python backend_driver_sgskip.py
popd

Statistiche GitHub #

Estraiamo automaticamente GitHub issue, PR e autori da GitHub tramite l'API. Copia la corrente doc/users/github_stats.rstin doc/users/prev_whats_new/github_stats_X.Y.Z.rst, modificando la destinazione del collegamento nella parte superiore del file e rimuovendo la sezione "Statistiche GitHub precedenti" alla fine.

Ad esempio, durante l'aggiornamento da v3.2.0 a v3.2.1:

cp doc/users/github_stats.rst doc/users/prev_whats_new/github_stats_3.2.0.rst
$EDITOR doc/users/prev_whats_new/github_stats_3.2.0.rst
# Change contents as noted above.
git add doc/users/prev_whats_new/github_stats_3.2.0.rst

Quindi rigenerare le statistiche aggiornate:

python tools/github_stats.py --since-tag v3.2.0 --milestone=v3.2.1 --project 'matplotlib/matplotlib' --links > doc/users/github_stats.rst

Esaminare e confermare le modifiche. Alcuni titoli di issue/PR potrebbero non essere reST validi (il problema più comune è *quello che viene interpretato come markup non chiuso).

Nota

Assicurati di eseguire l'autenticazione con l'API GitHub. In caso contrario, verrai bloccato da GitHub per aver superato i limiti di velocità dell'API. Puoi autenticarti in due modi:

  • utilizzando il keyringpacchetto; e poi quando esegui lo script delle statistiche, ti verrà richiesto il nome utente e la password, che verranno memorizzati nel tuo portachiavi di sistema, oppure,pip install keyring

  • utilizzando un token di accesso personale; genera un nuovo token in questa pagina GitHub con l' repo:public_repo ambito e posiziona il token in ~/.ghoauth.

Aggiorna e convalida i documenti #

Unisci *-docramo #

Unisci il ramo "doc" più recente (ad es. v3.2.0-doc) nel ramo su cui taggherai ed elimina il ramo doc su GitHub.

Aggiorna le versioni supportate in Criteri di sicurezza #

Quando si effettuano versioni principali o secondarie, aggiornare le versioni supportate nei criteri di sicurezza in SECURITY.md. Comunemente, può trattarsi di una o due versioni secondarie precedenti, ma dipende dai gestori delle versioni.

Aggiorna le note di rilascio #

Cosa c'è di nuovo #

Necessario solo per le versioni principali e secondarie. Le versioni di bugfix non dovrebbero avere nuove funzionalità.

Unisci il contenuto di tutti i file doc/users/next_whats_new/ in un unico file doc/users/prev_whats_new/whats_new_X.Y.0.rst ed elimina i singoli file.

Modifiche all'API #

Principalmente necessario per le versioni principali e secondarie. A volte potremmo avere modifiche API nelle versioni di correzione dei bug.

Unisci il contenuto di tutti i file doc/api/next_api_changes/ in un unico file doc/api/prev_api_changes/api_changes_X.Y.Z.rst ed elimina i singoli file.

Note di rilascio TOC #

Aggiorna doc/users/release_notes.rst:

  • Per le versioni principali e secondarie aggiungi una nuova sezione

    X.Y
===
.. toctree::
    :maxdepth: 1

    prev_whats_new/whats_new_X.Y.0.rst
    ../api/prev_api_changes/api_changes_X.Y.0.rst
    prev_whats_new/github_stats_X.Y.0.rst

  • Per le versioni di bugfix, aggiungi le statistiche GitHub e (se presenti) le modifiche API alla sezione XY esistente

    ../api/prev_api_changes/api_changes_X.Y.Z.rst
prev_whats_new/github_stats_X.Y.Z.rst

Aggiorna il commutatore di versione #

Aggiorna doc/_static/switcher.json. Se si tratta di una versione minore, X.Y.Z, crea una nuova voce e modifica il nome di stable . Se si tratta di una versione principale, , cambia il nome di e oltre ad aggiungere una nuova versione per la versione stabile precedente.version: X.Y.(Z-1)name: stable/X.Y.ZX.Y.0name: devel/X.(Y+1)name: stable/X.Y.0

Verifica che i documenti build #

Infine, assicurati che i documenti vengano compilati in modo pulito

make -Cdoc O=-j$(nproc) html latexpdf

Dopo aver creato i documenti, controlla che tutti i collegamenti, interni ed esterni, siano ancora validi. Usiamo linkcheckerper questo, che non è stato ancora portato su Python3. Dovrai creare un ambiente Python2 con requests==2.9.0e linkchecker

conda create -p /tmp/lnkchk python=2 requests==2.9.0
source activate /tmp/lnkchk
pip install linkchecker
pushd doc/build/html
linkchecker index.html --check-extern
popd

Affrontare eventuali problemi che possono sorgere. I collegamenti interni sono controllati su Circle CI, questo dovrebbe solo contrassegnare i collegamenti esterni non riusciti.

Aggiorna le versioni supportate in SECURITY.md #

Per il rilascio della versione secondaria, aggiornare la tabella SECURITY.mdper specificare che sono supportate le 2 versioni secondarie più recenti nella serie di versioni principali corrente.

Per una versione principale, aggiornare la tabella SECURITY.mdper specificare che l'ultima versione secondaria nella serie di versioni principali precedente è ancora supportata. L'eliminazione del supporto per l'ultima versione di una serie di versioni principali verrà gestita ad hoc.

Crea commit di rilascio e tag #

Per creare il tag, crea prima un commit vuoto con un insieme molto conciso delle note di rilascio nel messaggio di commit

git commit --allow-empty

e quindi creare un tag firmato e annotato con lo stesso testo nel corpo del messaggio

git tag -a -s v2.0.0

che richiederà la password della chiave GPG e un'annotazione. Per le versioni preliminari è importante seguirePEP 440 in modo che gli artefatti di build vengano ordinati correttamente in PyPI.

Per evitare problemi con eventuali builder downstream che scaricano il tarball da GitHub, è importante spostare tutti i rami lontano dal commit con il tag [ 1 ] :

git commit --allow-empty

Infine, invia il tag a GitHub:

git push DANGER main v2.0.0

Congratulazioni, la parte più spaventosa è fatta!

Se questa è una versione finale, crea anche un ramo 'doc' (questo non viene fatto per le versioni preliminari):

git branch v2.0.0-doc
git push DANGER v2.0.0-doc

e se si tratta di una versione maggiore o minore, crea anche un ramo di correzione dei bug (una micro versione verrà tagliata da questo ramo):

git branch v2.0.x

In questo ramo rimuovere il commento dai glob da Update e convalidare i documenti . Poi

git push DANGER v2.0.x

Gestione del rilascio / DOI #

Tramite l' interfaccia utente di GitHub , trasforma il tag appena inviato in una versione. Se questa è una pre-release, ricordati di contrassegnarla come tale.

Per le versioni finali, ottieni anche il DOI da zenodo (che ne produrrà uno automaticamente una volta inserito il tag). Aggiungi il doi post-fix e la versione al dizionario tools/cache_zenodo_svg.pyed esegui lo script.

Questo scaricherà il nuovo svg nella _staticdirectory nei documenti e modificherà il file doc/citing.rst. Esegui il commit del nuovo svg, la modifica in tools/cache_zenodo_svg.pye le modifiche in doc/citing.rstnel ramo VER-doc e invia a GitHub.

git checkout v2.0.0-doc
$EDITOR tools/cache_zenodo_svg.py
python tools/cache_zenodo_svg.py
$EDITOR doc/citing.html
git commit -a
git push DANGER v2.0.0-doc:v2.0.0-doc

Costruire binari #

Distribuiamo macOS, Windows e molte ruote Linux, nonché un tarball di origine tramite PyPI. La maggior parte dei builder dovrebbe attivarsi automaticamente una volta che il tag viene inviato a GitHub:

  • Windows, macOS e manylinux wheels sono costruiti su GitHub Actions. Le build vengono attivate dall'azione GitHub definita in .github/workflows/cibuildwheel.ymle le ruote saranno disponibili come artefatti della build.

  • Le ruote Windows alternative sono costruite automaticamente da Christoph Gohlke e saranno disponibili sul suo sito una volta costruite.

  • Il bot di spunta automatica dovrebbe aprire una richiesta pull nel feedstock conda-forge . Rivedi e unisci (se ne hai il potere).

Avvertimento

Poiché questo è automatizzato, è estremamente importante allontanare tutti i rami dal tag come discusso in Create release commit and tag .

Se si tratta di una versione finale, è necessario contattare i seguenti pacchetti downstream:

  • Debian

  • Federa

  • Arco

  • Gentoo

  • Macport

  • Birra casalinga

  • Continuo

  • Pensiero

Questo può essere fatto prima di raccogliere tutti i binari e caricarli su pypi.

Effettua la distribuzione e carica su PyPI #

Una volta che hai raccolto tutte le ruote (aspettati che questo richieda circa un giorno), genera il tarball

git checkout v2.0.0
git clean -xfd
python setup.py sdist

e copia tutte le ruote nella distdirectory. Innanzitutto, controlla che i file dist siano OK

twine check dist/*

e quindi utilizzare twineper caricare tutti i file su pypi

twine upload -s dist/matplotlib*tar.gz
twine upload dist/*whl

Congratulazioni, ora hai fatto la seconda parte più spaventosa!

Crea e distribuisci la documentazione #

Per creare la documentazione devi avere la versione con tag installata, ma crea i documenti dal ver-docramo. Un modo semplice per organizzare questo è:

pip install matplotlib
pip install -r requirements/doc/doc-requirements.txt
git checkout v2.0.0-doc
git clean -xfd
make -Cdoc O="-t release -j$(nproc)" html latexpdf LATEXMKOPTS="-silent -f"

che costruirà sia la versione html che pdf della documentazione.

La documentazione compilata esiste nel repository matplotlib.github.com . Il push delle modifiche a main aggiorna automaticamente il sito web.

La documentazione è organizzata per versione. Alla radice dell'albero c'è sempre la documentazione per l'ultima versione stabile. Al di sotto di ciò, ci sono directory contenenti la documentazione per le versioni precedenti. La documentazione per current main è costruita su Circle CI e inviata al repository devdocs . Questi sono disponibili su matplotlib.org/devdocs .

Supponendo che tu abbia estratto questo repository nella stessa directory di matplotlib

cd ../matplotlib.github.com
mkdir 2.0.0
rsync -a ../matplotlib/doc/build/html/* 2.0.0
cp ../matplotlib/doc/build/latex/Matplotlib.pdf 2.0.0

che copierà i documenti creati. Se si tratta di una versione finale, collega la stablesottodirectory alla versione più recente:

rsync -a 2.0.0/* ./
rm stable
ln -s 2.0.0/ stable

Dovrai modificare manualmente versions.htmlper mostrare le ultime 3 versioni con tag. Dovrai anche modificare sitemap.xmlper includere la versione appena rilasciata. Ora esegui il commit e invia tutto a GitHub

git add *
git commit -a -m 'Updating docs for v2.0.0'
git push DANGER main

Congratulazioni, ora hai completato la terza parte più spaventosa!

Se hai accesso, cancella le cache di Cloudflare.

In genere GitHub impiega circa 5-10 minuti per elaborare il push e aggiornare la pagina Web live (ricordarsi di svuotare la cache del browser).

Annunciando #

Il passo finale è annunciare il rilascio al mondo. Una versione breve delle note di rilascio insieme ai ringraziamenti dovrebbe essere inviata a

Per le versioni finali gli annunci devono essere inviati anche alle mailing list numpy/scipy/scikit-image.

Inoltre, gli annunci dovrebbero essere fatti sui social network (Twitter tramite l' @matplotlibaccount, qualsiasi altro tramite account personali). NumFOCUS dovrebbe essere contattato per l'inclusione nella loro newsletter.

Conda pacchetti #

Il progetto Matplotlib stesso non rilascia pacchetti conda. In particolare, il gestore di rilascio di Matplotlib non è responsabile della creazione di pacchetti conda.

Per informazioni sulla confezione di Matplotlib per conda-forge vedere https://github.com/conda-forge/matplotlib-feedstock .