Ir para o conteúdo

Submeter um pedido de puxar

Agora que confirmou todas as suas alterações, está pronto para enviar um pedido de puxar. Para garantir um processo de revisão tranquilo, há uma série de passos que deve seguir.

Trabalhar com pré-submissão

Quando submete qualquer alteração, a pré-submissão é executada automaticamente. Se houver algum problema encontrado com a submissão, isso fará com que a submissão falhe. Sempre que possível, a pré-submissão fará as alterações necessárias para corrigir os problemas encontrados. No exemplo a seguir, um problema de formatação de código foi encontrado pela verificação ruff:

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Falhad
- hook id: ruff-format
- foram modificados ficheiros por este gancho

1 ficheiro reformatado, 488 ficheiros não alterados

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Falhad
- hook id: ruff-format
- foram modificados ficheiros por este gancho

1 ficheiro reformatado, 488 ficheiros não alterados

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...> git add some/interesting_file.py
(.venv) C:\...> git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Falhad
- hook id: ruff-format
- foram modificados ficheiros por este gancho

1 ficheiro reformatado, 488 ficheiros não alterados

ruff check...............................................................Passed
codespell................................................................Passed

Nesse caso, o ruff corrigiu automaticamente o problema; portanto, pode adicionar novamente todos os ficheiros que foram modificados como resultado das verificações de pré-submissão e confirmar novamente a alteração. Entretanto, algumas verificações vão exigir que faça modificações manuais. Depois de fazer essas alterações, adicione novamente os ficheiros modificados e faça a submissão novamente.

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 ficheiro alterado, 4 inseridos(+), 2 apagados(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 ficheiro alterado, 4 inseridos(+), 2 apagados(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 ficheiro alterado, 4 inseridos(+), 2 apagados(-)

Quando tudo for aprovado, verá uma mensagem indicando que a submissão foi finalizada, e o registo do git vai mostrar a submissão como a adição mais recente. Agora está pronto para empurrar para o GitHub.

Envie suas alterações para o GitHub e crie o seu pedido de puxar

Na primeira vez que empurrar para o GitHub, vai receber um URL que o vai levar diretamente à página do GitHub para criar um novo pedido de puxar. Siga p URL e crie o seu pedido de puxar.

O seguinte mostra um exemplo do que esperar do push, com o URL destacado.

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

Se já tiver feito push do ramo atual para o GitHub, não vai receber o URL novamente. No entanto, há outras maneiras de aceder ao URL de criação de PR:

  • Navegue até o repositório do autor, clique em "Pull Requests", seguido de "New pull request" (Nova solicitação de puxar) e escolha a partir da qual deseja enviar o pedido de puxar.
  • Se fez push recentemente, navegue até o repositório do autor, localize a faixa acima da lista de ficheiros que indica que o repositório "teve pushes recentes" e clique no botão "Compare & pull request".
  • Use o comando gh pr create --web da CLI do GitHub para abrir um navegador Web na página de criação de PR.

A CLI do GitHub: gh

O GitHub fornece a CLI GitHub, que lhe dá acesso a muitos dos recursos do GitHub a partir do seu terminal, por meio do comando gh. A Documentação da CLI do GitHub cobre todas as funcionalidades.

gh pr create

Não use o comando gh pr create sozinho para criar o seu pedido de puxar. Os projetos do BeeWare utilizam um modelo para pedidos de puxar, e exigimos que todas as contribuições sigam esse modelo. O comando gh pr create contorna o uso desse modelo.

Conteúdo do pedido de puxar

O título de um pedido de puxar deve ser informativo, claro e conciso. Tente manter-lo curto se possível, mas títulos mais longos são aceitáveis, se tal for necessário. Um bom título de PR deve dar a uma pessoa sem nenhum contexto uma ideia razoavelmente sólida do bug ou funcionalidade implementada pelo seu PR.

O seu pedido de puxar tem de seguir o modelo de pedido de puxar do BeeWare. Se criou o seu pedido de puxar usando a interface web do GitHub, esse modelo será fornecido como ponto de partida para a descrição do seu pedido. Se por engano criar um pedido de puxar sem usar esse modelo, poderá edita-lo para adicionar o conteúdo do modelo — mas o conteúdo do modelo tem de ser fornecido e preenchido corretamente.

A descrição do PR deve refletir claramente as alterações no PR. Uma pessoa sem qualquer contexto deve ser capaz de ler a sua descrição e obter uma compreensão relativamente completa do motivo pelo qual a alteração está a ser feita. Evite piadas, expressões idiomáticas, expressões coloquiais e formatação desnecessária, como o uso de letras maiúsculas ou pontuação excessiva; o objetivo é explicar de forma direta o que está a acontecer no seu PR, e evitar esses elementos torna a descrição mais acessível a outras pessoas.

Se houver algum caso de reprodução ou qualquer regime de teste que tenha usado e que ainda não faça parte das alterações presentes no PR, eles devem ser explicados e incluídos no PR. A explicação deve incluir como executa-los e o que fazer para reproduzir o resultado desejado.

Se o seu pedido de puxar resolver o problema nº 1234, deve incluir o texto Fixes #1234 na descrição do pedido de puxar. Isso vai fazer com que o problema seja fechado automaticamente quando o pedido de puxar for fundido. Pode fazer referência a outras discussões, problemas ou pedidos de puxar usando a mesma sintaxe #1234. Pode referir-se a um problema num repositório diferente prefixando o número com - por exemplo, python/cpython#1234 se estiver a referir ao problema 1234 no repositório CPython.

As ferramentas de IA são muito suscetíveis de escrever mensagens de pedido de puxar muito detalhadas e pouco úteis. Se usar uma ferramenta de IA para gerar seu PR, você é responsável por garantir que a descrição do pedido de puxar seja concisa e contenha apenas informações úteis para o processo de revisão. Não precisa, por exemplo, incluir detalhes sobre um “regime de testes” que descreva como executar o conjunto de testes, nem uma “justificação” para explicar porque um bug precisa ser corrigido. Corpos de pedidos de puxar excessivamente detalhados podem resultar no fechar do seu pedido de puxar sem que ele seja revisto, pois não respeitam os recursos limitados da equipa principal.

O modelo de Pedido de Puxar do BeeWare

O modelo de pedido de puxar do BeeWare não é opcional. Exigimos que todos os pedidos de puxar sigam este modelo. O seu pedido não vai ser analisado se estiver a faltar a secção “Lista de verificação de PR”, ou se suas respostas às perguntas com caixas de seleção estiverem incompletas ou inconsistentes. Se usou uma ferramenta de IA para gerar o seu pedido de puxar, você tem de marcar a caixa relevante e fornecer detalhes na linha “Assistido por:”.

Integração contínua

Integração contínua, ou CI, é o processo de executar verificações automatizadas no seu pedido de puxar. Isso pode incluir verificações simples, como garantir que o código esteja formatado corretamente, mas também inclui a execução do conjunto de testes e a criação de documentação.

Há um grande número de alterações que podem resultar em falhas de CI. Em termos gerais, não revemos um PR que não esteja aprovado na CI. Se criar um pedido de puxar e a CI falhar, não vamos iniciar a sua análise até que seja aprovado. Se as suas alterações resultarem numa falha, é da sua responsabilidade investigar o motivo e resolver o problema.

Quando o CI falhar, os atalhos de falha vão aparecer na parte inferior da página PR, sob o título "Algumas verificações não foram bem-sucedidas". Vai ver uma lista de verificações com falha, que aparecerá no topo da lista de todas as verificações se também houver verificações aprovadas. Se clicar no atalho de falha, será levado ao registo. O registo geralmente fornece todas as informações necessárias para descobrir o que causou a falha. Leia o registo e tente descobrir porque a falha está a ocorrer, e depois faça o que for necessário para resolve-la.

Ocasionalmente, uma verificação de CI vai falhar por motivos que não estão relacionados às suas alterações. Isso pode ocorrer devido a um problema na máquina que executa a verificação de CI ou porque uma verificação de CI é instável. Se observar uma falha e tiver certeza de que ela não está relacionada às suas alterações, adicione um comentário ao seu PR para esse fim e nós analisaremos o caso.

Para acionar uma nova execução de CI, precisa empurrar as novas alterações para o seu ramo.

Se encontrar-se numa situação em que precisa de ajuda para fazer com que o CI seja aprovado, deixe um comentário no PR a informar-nos e faremos o possível para ajudar.

As verificações pre-commit e towncrier

Se as verificações pre-commit ou towncrier falharem, isso vai impedir a execução da maioria das demais verificações de CI. Você vai precisar resolver os problemas aplicáveis antes que o conjunto completo de verificações seja executado.

Temos recursos limitados de CI. É importante entender que toda vez que fizer push para o ramo, a CI será iniciada. Se for fazer várias alterações, é melhor fazer essas alterações localmente e envia-las todas de uma vez. O CI só será executado na submissão mais recente num lote, minimizando a carga no nosso sistema de CI.

O processo de submeter o seu PR não é concluído até que seja aprovado pelo CI ou até que forneça uma explicação do motivo pelo qual não foi aprovado.

O seu pedido de puxar pode exigir conteúdo adicional, como uma nota de alteração, antes de poder ser revisado.