Guia de lançamento #

Este documento é relevante apenas para gerenciadores de versão do Matplotlib.

Um guia para desenvolvedores que estão fazendo uma versão do Matplotlib.

Observação

Isso pressupõe que um remoto somente leitura para o repositório canônico é remotee um remoto de leitura/gravação éDANGER

Teste #

Usamos o GitHub Actions para integração contínua. Ao se preparar para um lançamento, o commit marcado final deve ser testado localmente antes de ser carregado:

pytest -n 8 .

Além disso, o seguinte teste deve ser executado e inspecionado manualmente:

python tools/memleak.py agg 1000 agg.pdf

Além disso, o seguinte deve ser executado e inspecionado manualmente, mas atualmente está quebrado:

pushd examples/tests/
python backend_driver_sgskip.py
popd

Estatísticas do GitHub #

Extraímos automaticamente problemas, PRs e autores do GitHub por meio da API. Copie o atual doc/users/github_stats.rstpara doc/users/prev_whats_new/github_stats_X.Y.Z.rst, alterando o destino do link na parte superior do arquivo e removendo a seção "Estatísticas anteriores do GitHub" no final.

Por exemplo, ao atualizar de v3.2.0 para 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

Em seguida, gere novamente as estatísticas atualizadas:

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

Revise e confirme as alterações. Alguns títulos de problema/PR podem não ser reST válidos (o problema mais comum *é interpretado como marcação não fechada).

Observação

Certifique-se de autenticar na API do GitHub. Caso contrário, você será bloqueado pelo GitHub por ultrapassar os limites de taxa da API. Você pode autenticar de duas maneiras:

  • usando o keyringpacote; e então, ao executar o script de estatísticas, você será solicitado a fornecer o nome de usuário e a senha, que serão armazenados no chaveiro do sistema ou,pip install keyring

  • usando um token de acesso pessoal; gere um novo token nesta página do GitHub com o repo:public_repo escopo e coloque o token em ~/.ghoauth.

Atualize e valide os documentos #

Mesclar *-docramificação #

Mescle o branch 'doc' mais recente (por exemplo, v3.2.0-doc) no branch que você vai marcar e exclua o branch doc no GitHub.

Atualize as versões suportadas na política de segurança #

Ao fazer versões principais ou secundárias, atualize as versões com suporte na Política de segurança em SECURITY.md. Geralmente, isso pode ser uma ou duas versões secundárias anteriores, mas depende dos gerentes de versão.

Atualizar notas de versão #

o que há de novo #

Necessário apenas para versões principais e secundárias. As versões de bugfix não devem ter novos recursos.

Mescle o conteúdo de todos os arquivos em doc/users/next_whats_new/ um único arquivo doc/users/prev_whats_new/whats_new_X.Y.0.rst e exclua os arquivos individuais.

Alterações de API #

Principalmente necessário para versões principais e secundárias. Às vezes, podemos ter alterações de API em lançamentos de correções de bugs.

Mescle o conteúdo de todos os arquivos em doc/api/next_api_changes/ um único arquivo doc/api/prev_api_changes/api_changes_X.Y.Z.rst e exclua os arquivos individuais.

Notas de lançamento TOC #

Atualização doc/users/release_notes.rst:

  • Para versões principais e secundárias, adicione uma nova seção

    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

  • Para lançamentos de correções de bugs, adicione as estatísticas do GitHub e (se houver) as alterações da API na seção XY existente

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

Atualizar o alternador de versão #

Atualizar doc/_static/switcher.json. Se for uma versão secundária X.Y.Z, crie uma nova entrada e altere o nome de estável . Se for um lançamento principal , altere o nome e adicione uma nova versão para o estável anterior.version: X.Y.(Z-1)name: stable/X.Y.ZX.Y.0name: devel/X.(Y+1)name: stable/X.Y.0

Verifique se os documentos compilam #

Por fim, certifique-se de que os documentos sejam compilados de forma limpa

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

Depois que os documentos forem criados, verifique se todos os links, internos e externos, ainda são válidos. Usamos linkcheckerpara isso, que ainda não foi portado para Python3. Você precisará criar um ambiente Python2 com 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

Resolva quaisquer problemas que possam surgir. Os links internos são verificados no Circle CI, isso deve apenas sinalizar links externos com falha.

Atualize as versões suportadas em SECURITY.md #

Para lançamento de versão secundária, atualize a tabela SECURITY.mdpara especificar que os 2 lançamentos secundários mais recentes na série de versão principal atual são suportados.

Para uma liberação de versão principal, atualize a tabela SECURITY.mdpara especificar que a última versão secundária na série de versão principal anterior ainda é suportada. A eliminação do suporte para a última versão de uma série de versões principais será tratada de forma ad hoc.

Criar confirmação de lançamento e tag #

Para criar a tag, primeiro crie um commit vazio com um conjunto muito conciso das notas de lançamento na mensagem do commit

git commit --allow-empty

e, em seguida, crie uma tag assinada e anotada com o mesmo texto no corpo da mensagem

git tag -a -s v2.0.0

que solicitará sua senha de chave GPG e uma anotação. Para pré-lançamentos é importante seguirPEP 440 para que os artefatos de compilação sejam classificados corretamente no PyPI.

Para evitar problemas com quaisquer construtores downstream que baixam o tarball do GitHub, é importante mover todas as ramificações para longe do commit com a tag [ 1 ] :

git commit --allow-empty

Por fim, envie a tag para o GitHub:

git push DANGER main v2.0.0

Parabéns, a parte mais assustadora está feita!

Se esta for uma versão final, crie também uma ramificação 'doc' (isso não é feito para pré-lançamentos):

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

e se esta for uma versão principal ou secundária, crie também uma ramificação de correção de bug (uma micro versão será cortada desta ramificação):

git branch v2.0.x

Nesta ramificação, descomente os globs de Update e valide os documentos . E depois

git push DANGER v2.0.x

Gerenciamento de liberação / DOI #

Por meio da IU do GitHub , transforme a tag recém-enviada em uma versão. Se este for um pré-lançamento, lembre-se de marcá-lo como tal.

Para lançamentos finais, obtenha também o DOI do zenodo (que produzirá automaticamente um assim que a tag for pressionada). Adicione o post-fix e a versão doi ao dicionário tools/cache_zenodo_svg.pye execute o script.

Isso fará o download do novo svg para o _staticdiretório nos documentos e editará doc/citing.rst. Confirme o novo svg, a alteração para tools/cache_zenodo_svg.py, e as alterações para doc/citing.rsta ramificação VER-doc e envie para o 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

Construindo binários #

Distribuímos macOS, Windows e muitas rodas Linux, bem como um tarball de origem via PyPI. A maioria dos construtores deve ser acionada automaticamente assim que a tag for enviada ao GitHub:

  • Windows, macOS e muitas rodas linux são construídas no GitHub Actions. Os builds são acionados pela GitHub Action definida em .github/workflows/cibuildwheel.yml, e as rodas estarão disponíveis como artefatos do build.

  • Rodas alternativas do Windows são construídas por Christoph Gohlke automaticamente e estarão disponíveis em seu site assim que construídas.

  • O bot de auto-tick deve abrir uma solicitação pull na matéria-prima conda-forge . Revise e mescle (se você tiver o poder).

Aviso

Como isso é automatizado, é extremamente importante remover todas as ramificações da tag, conforme discutido em Criar commit de release e tag .

Se esta for uma versão final, os seguintes empacotadores downstream devem ser contatados:

  • Debian

  • Fedora

  • Arco

  • Gentoo

  • Macports

  • Homebrew

  • contínuo

  • pensado

Isso pode ser feito antes de coletar todos os binários e fazer o upload para o pypi.

Faça a distribuição e faça o upload para o PyPI #

Depois de coletar todas as rodas (espere que isso leve cerca de um dia), gere o tarball

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

e copie todas as rodas para o distdiretório. Primeiro, verifique se os arquivos dist estão OK

twine check dist/*

e então use twinepara carregar todos os arquivos para o pypi

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

Parabéns, agora você fez a segunda parte mais assustadora!

Construir e implantar documentação #

Para compilar a documentação, você deve ter a versão marcada instalada, mas compilar os documentos a partir do ver-docbranch. Uma maneira fácil de organizar isso é:

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"

que criará as versões html e pdf da documentação.

A documentação construída existe no repositório matplotlib.github.com . O envio de alterações para principal atualiza automaticamente o site.

A documentação está organizada por versão. Na raiz da árvore está sempre a documentação da versão estável mais recente. Abaixo dele, existem diretórios contendo a documentação para versões mais antigas. A documentação para o main atual é construída no Circle CI e enviada para o repositório devdocs . Eles estão disponíveis em matplotlib.org/devdocs .

Supondo que você tenha feito check-out deste repositório no mesmo diretório que 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

que irá copiar os documentos construídos. Se esta for uma versão final, vincule o stablesubdiretório à versão mais recente:

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

Você precisará editar manualmente versions.htmlpara mostrar as últimas 3 versões marcadas. Você também precisará editar sitemap.xmlpara incluir a versão recém-lançada. Agora confirme e envie tudo para o GitHub

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

Parabéns, você fez a terceira parte mais assustadora!

Se você tiver acesso, limpe os caches do Cloudflare.

Normalmente, leva de 5 a 10 minutos para o GitHub processar o envio e atualizar a página da Web ao vivo (lembre-se de limpar o cache do navegador).

Anunciando #

O passo final é anunciar o lançamento para o mundo. Uma versão resumida das notas de lançamento junto com os agradecimentos deve ser enviada para

Para os lançamentos finais, os anúncios também devem ser enviados para as listas de discussão numpy/scipy/scikit-image.

Além disso, os anúncios devem ser feitos nas redes sociais (twitter via @matplotlibconta, qualquer outro via contas pessoais). NumFOCUS deve ser contactado para inclusão na sua newsletter.

Pacotes Conda #

O próprio projeto Matplotlib não libera pacotes conda. Em particular, o gerenciador de lançamento do Matplotlib não é responsável pelo empacotamento conda.

Para obter informações sobre a embalagem do Matplotlib para conda-forge, consulte https://github.com/conda-forge/matplotlib-feedstock .