Diretrizes de solicitação pull #

As solicitações pull (PRs) são o mecanismo para contribuir com o código e a documentação do Matplotlibs.

Resumo para autores de pull request #

Observação

  • Valorizamos as contribuições de pessoas com todos os níveis de experiência. Em particular, se este for seu primeiro PR, nem tudo precisa ser perfeito. Vamos orientá-lo através do processo de relações públicas.

  • No entanto, tente seguir as diretrizes abaixo da melhor maneira possível para ajudar a tornar o processo de RP rápido e tranquilo.

  • Seja paciente com os revisores. Fazemos o possível para responder rapidamente, mas temos largura de banda limitada. Se não houver feedback dentro de alguns dias, envie-nos um ping postando um comentário em seu PR.

Ao fazer um PR, preste atenção a:

  • Alvo o ramo principal .

  • Siga as diretrizes de codificação .

  • Atualize a documentação, se necessário.

  • Procure tornar o PR o mais "pronto para uso" possível. Isso ajuda a acelerar o processo de revisão.

  • Não há problema em abrir PRs incompletos ou em andamento se precisar de ajuda ou feedback dos desenvolvedores. Você pode marcá-los como solicitações pull de rascunho no GitHub.

  • Ao atualizar seu PR, em vez de adicionar novos commits para corrigir algo, considere alterar seu(s) commit(s) inicial(is) para manter o histórico limpo. Você pode conseguir isso usando

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

Veja também Contribuindo para saber como fazer um PR.

Resumo para revisores de pull request #

Observação

  • Se você tem direitos de commit, então você é confiável para usá-los. Por favor, ajude a revisar e mesclar PRs!

  • Seja paciente e gentil com os contribuidores.

Tópicos de conteúdo:

Tópicos organizacionais:

Diretrizes detalhadas #

Documentação #

  • Cada novo recurso deve ser documentado. Se for um novo módulo, não se esqueça de adicionar um novo primeiro arquivo aos documentos da API.

  • Cada função de plotagem de alto nível deve ter um pequeno exemplo na Examplesseção do docstring. Isso deve ser o mais simples possível para demonstrar o método. Exemplos mais complexos devem ir para um arquivo de exemplo dedicado no examplesdiretório, que será renderizado na galeria de exemplos na documentação.

  • Crie os documentos e certifique-se de que todos os avisos de formatação sejam abordados.

  • Consulte Escrevendo documentação para nosso guia de estilo de documentação.

  • Se sua alteração for um novo recurso importante, adicione uma entrada a doc/users/whats_new.rst.

  • Se você alterar a API de maneira incompatível com versões anteriores, documente-a adicionando um arquivo no subdiretório relevante de doc/api/next_api_changes/, provavelmente no behavior/ subdiretório.

Rótulos #

  • Se você tiver o direito de definir rótulos, marque o PR com rótulos descritivos. Veja a lista de rótulos .

  • Se o PR fizer alterações na Ação de construção da roda, adicione o rótulo "Executar roda cibuild" para habilitar rodas de teste.

Marcos #

  • Defina o marco de acordo com estas regras:

    • Novos recursos e alterações de API são marcados para o próximo lançamento menor v3.X.0.

    • Correções de bugs e alterações de docstring são marcadas para o próximo lançamento de patchv3.X.Y

    • Alterações na documentação (todos os arquivos .rst e exemplos) são marcados v3.X-doc

    Se várias regras se aplicarem, escolha a primeira correspondência na lista acima.

    A definição de um marco não implica ou garante que um PR será mesclado para essa versão, mas se fosse mesclado em qual versão ele estaria.

    Todos esses PRs devem ter como alvo a filial principal. A tag de marco aciona um backport automático para marcos que possuem uma ramificação correspondente.

Mesclando #

  • Documentação e exemplos podem ser mesclados pelo primeiro revisor. Use o limite "isso é melhor do que era?" como critério de revisão.

  • Para alterações de código (qualquer coisa em srcou lib) pelo menos dois desenvolvedores principais (aqueles com direitos de confirmação) devem revisar todas as solicitações pull. Se você for o primeiro a revisar um PR e aprovar as alterações, use a ferramenta 'aprovar revisão' do GitHub para marcá-lo como tal. Se você for um revisor subseqüente, aprove a revisão e, se achar que não é necessária mais nenhuma revisão, una o PR.

    Certifique-se de que todas as alterações da API sejam documentadas em um arquivo em um dos subdiretórios de doc/api/next_api_changese que novos recursos significativos tenham uma entrada em doc/user/whats_new.

    • Se um PR já tiver uma revisão positiva, um desenvolvedor principal (por exemplo, o primeiro revisor, mas não necessariamente) pode defender esse PR para a fusão. Para fazer isso, eles devem executar ping em todos os desenvolvedores principais no GitHub e na lista de discussão de desenvolvedores e rotular o PR com "Mesclar com revisão única?" etiqueta. Outros desenvolvedores principais podem revisar o PR e mesclar ou rejeitá-lo, ou simplesmente solicitar que ele receba uma segunda revisão antes de ser mesclado. Se ninguém solicitar essa segunda revisão dentro de uma semana, o PR poderá ser mesclado com base nessa única revisão.

      Um desenvolvedor principal deve defender apenas um PR por vez e devemos tentar manter o fluxo de PRs defendidos razoável.

  • Não faça a mesclagem automática, exceto para patches 'pequenos' para desfazer a quebra do IC ou quando outro revisor permitir explicitamente (por exemplo, "Aprovar a passagem do módulo CI, pode mesclar automaticamente quando verde").

Testes automatizados #

Sempre que uma solicitação pull é criada ou atualizada, várias ferramentas de teste automatizadas serão executadas em todas as plataformas e versões suportadas do Python.

  • Certifique-se de que os pipelines Linting, GitHub Actions, AppVeyor, CircleCI e Azure estejam passando antes da mesclagem (todas as verificações estão listadas na parte inferior da página do GitHub da sua solicitação pull). Aqui estão algumas dicas para encontrar a causa da falha do teste:

    • Se o Linting falhar, você terá um problema de estilo de código, que será listado como anotações no diff da solicitação pull.

    • Se uma execução do GitHub Actions ou do AppVeyor falhar, procure no log por FAILURES. A seção subseqüente conterá informações sobre os testes com falha.

    • Se o CircleCI falhar, provavelmente você tem algum problema de estilo reStructuredText nos documentos. Pesquise no log do CircleCI por WARNING.

    • Se os pipelines do Azure falharem com um erro de comparação de imagem, você poderá localizar as imagens como artefatos do trabalho do Azure:

      • Clique em Detalhes na verificação na página GitHub PR.

      • Clique em Exibir mais detalhes no Azure Pipelines para acessar o Azure.

      • Na página de visão geral, os artefatos são listados na seção Relacionados .

  • Codecov e LGTM são atualmente apenas para informação. Sua falha não é necessariamente um bloqueador.

  • tox não é usado no teste automatizado. É suportado para testes localmente.

  • Se você sabe que suas alterações não precisam ser testadas (isso é muito raro!), todos os ICs podem ser ignorados para um determinado commit incluindo ou na mensagem de commit. Se você souber que apenas um subconjunto de ICs precisa ser executado (por exemplo, se estiver alterando algum bloco de reStructuredText simples e deseja que apenas o CircleCI seja executado para renderizar o resultado), os ICs individuais também podem ser ignorados em confirmações individuais usando o seguinte substrings em mensagens de commit:[ci skip][skip ci]

    • Ações do GitHub:[skip actions]

    • AppVeyor: (deve estar na primeira linha do commit)[skip appveyor]

    • Pipelines do Azure:[skip azp]

    • Círculo CI:[skip circle]

Número de commits e esmagamento #

  • O esmagamento é caso a caso. O equilíbrio está entre a carga do contribuidor, mantendo um histórico relativamente limpo e mantendo um histórico utilizável para divisão. A única vez em que somos realmente rigorosos sobre isso é para eliminar arquivos binários (por exemplo, várias regenerações de imagem de teste) e remover fusões upstream.

  • Não deixe que o perfeito seja inimigo do bom, especialmente para documentação ou exemplos de relações públicas. Se você estiver fazendo muitas pequenas sugestões, abra um PR no branch original, envie as alterações para o branch contribuidor ou mescle o PR e abra um novo PR no upstream.

  • Se você enviar para um ramo colaborador, deixe um comentário explicando o que você fez, por exemplo "Tomei a liberdade de enviar um pequeno PR de limpeza para o seu ramo, obrigado pelo seu trabalho.". Se você pretende fazer alterações substanciais no código ou na intenção do PR, verifique primeiro com o colaborador.

Ramos e backports #

Filiais atuais #

Os ramos ativos atuais são

a Principal

A versão de desenvolvimento atual. Versões secundárias futuras ( v3.N.0 ) serão ramificadas disso.

v3.Nx

Ramo de manutenção para Matplotlib 3.N. Futuras versões de patch serão derivadas disso.

v3.NM-doc

Documentação para a versão atual. Em uma versão de patch, isso será substituído por uma ramificação nomeada corretamente para a nova versão.

Seleção de ramificação para solicitações pull #

Geralmente, todas as solicitações pull devem ter como alvo a ramificação principal.

Os demais ramos são alimentados de forma automática ou manual . O direcionamento direto para outras filiais raramente é necessário para trabalhos especiais de manutenção.

Estratégia de backport #

Sempre faremos backport para o ramo de lançamento do patch ( v3.Nx ):

  • correções de bugs críticos (segfault, falha na importação, coisas que o usuário não pode contornar)

  • correções para regressões contra os dois últimos lançamentos.

Todo o resto (regressões contra versões mais antigas, bugs/inconsistências de API que o usuário pode contornar em seu código) é analisado caso a caso, deve ser de baixo risco e precisa de alguém para defender e orientar o backport.

As únicas alterações a serem portadas para o ramo de documentação ( v3.NM-doc ) são alterações em doc, examplesou tutorials. Quaisquer alterações libou srcincluindo alterações apenas de docstring não devem ser portadas para esta ramificação.

Backports automatizados #

Usamos o bot meeseeksdev para fazer o backport automaticamente das mesclagens para a base correta do branch de manutenção no marco. Para funcionar corretamente, o marco deve ser definido antes da fusão. Se você tiver direitos de confirmação, o bot também pode ser acionado manualmente após uma mesclagem, deixando uma mensagem no PR. Se houver conflitos, meeseekdevs informará que o backport precisa ser feito manualmente.@meeseeksdev backport to BRANCH

A ramificação de destino é configurada colocando a descrição do marco em sua própria linha.on-merge: backport to TARGETBRANCH

Se o bot não estiver funcionando conforme o esperado, informe os problemas ao Meeseeksdev .

Backports manuais #

Ao fazer backports, copie o formulário usado por meeseekdev, . Se você precisar resolver conflitos manualmente, anote-os e como você os resolveu na mensagem de confirmação.Backport PR #XXXX: TITLE OF PR

Fazemos um backport de main para v2.2.x assumindo:

  • matplotlibé uma ramificação remota somente leitura do repositório matplotlib/matplotlib

O TARGET_SHAé o hash do commit de mesclagem que você gostaria de fazer o backport. Isso pode ser lido na página GitHub PR (na interface do usuário com a notificação de mesclagem) ou por meio das ferramentas git CLI.

Supondo que você já tenha uma ramificação local v2.2.x(se não, então ) e que seu apontador remoto para seja chamado :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

Arquivos com conflitos podem ser listados por , e deverão ser corrigidos manualmente (pesquise em ). Assim que o conflito for resolvido, você terá que adicionar novamente o(s) arquivo(s) ao branch e então continuar a escolha de dedo:git status>>>>>

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

Use seu critério para empurrar diretamente para upstream ou abrir um PR; certifique-se de empurrar ou PR contra o v2.2.xramo upstream, não main!