Ir para o conteúdo

Corrigir um problema

BeeWare segue uma lista de problemas conhecidos. Qualquer um destes problemas é candidato a ser trabalhado.

Esta lista pode ser filtrada de várias maneiras. Por exemplo, pode filtrar por plataforma, para que possa se concentrar nos problemas que afetam as plataformas em que pode testar; ou pode filtrar por tipo de problema, como bugs de documentação. Há também um filtro para boas primeiras edições - estes são problemas que foram identificados como problemas que têm uma causa conhecida, e acreditamos que a correção deve ser relativamente simples (embora possamos estar errados na nossa análise).

Se um problema tiver mais de 6 meses, é perfeitamente possível que ele tenha sido resolvido, portanto, a primeira etapa é verificar se pode reproduzir o problema. Use as informações fornecidas no relatório de bug para tentar reproduzir o problema. Se não conseguir reproduzir o problema, informe o que encontrou como um comentário sobre o problema e escolha outro problema.

Se puder reproduzir o problema, tente corrigi-lo! Descubra qual combinação de código está a implementar o recurso e veja se consegue descobrir o que não está a funcionar corretamente.

Mesmo que não consiga corrigir o problema, vale a pena relatar tudo o que descobrir durante o processo como um comentário sobre o problema. Se conseguir encontrar a origem do problema, mas não a correção, esse conhecimento geralmente será suficiente para que alguém que saiba mais sobre uma plataforma resolva o problema. Se o problema ainda não tiver um bom caso de reprodução (uma pequena aplicação de amostra que não faz nada além de reproduzir o problema), fornecer uma pode ser de grande ajuda.

Contribuir com uma correção de problema

Configurar um ambiente de desenvolvimento

Configurar um ambiente de desenvolvimento

Os passos para configurar um ambiente de desenvolvimento variam de acordo com o projeto para o qual está a contribuir. Escolha a partir do seguinte:

Se o repositório para o qual deseja contribuir não estiver nesta lista, siga o guia de desenvolvimento do projeto mais relevante. Por exemplo, se você quiser trabalhar num repositório de modelos do Briefcase, deve seguir o guia do Briefcase.

Trabalhar a partir de um ramo

Trabalhe a partir de um ramo de recurso, não do seu ramo principal ou main

Antes de começar a trabalhar na sua alteração, certifique-se de ter criado um ramo. Por predefinição, quando faz clone da bifurcação do seu repositório, faz checkout no ramo main. Isto é uma cópia direta do ramo main de BeeWare.

Apesar de poder enviar um pedido de puxar do seu ramo main, é preferível não o fazer. Se enviar um pedido de puxar que esteja quase correto, o membro da equipa principal que rever o seu pedido de puxar pode ser capaz de fazer as alterações necessárias, em vez de fornecer retorno a solicitar uma pequena alteração. No entanto, se enviar um pedido de puxar do seu ramo main, os revisores vão ser impedidos de fazer modificações.

Trabalhar no seu ramo principal também torna difícil para si depois de concluir o primeiro pedido de puxar. Se quiser trabalhar num segundo pedido de puxar, vai precisar ter uma cópia "limpa" do ramo principal do projeto do autor no qual basear a sua segunda contribuição; se fez a sua primeira contribuição a partir do ramo main, não vai ter mais essa versão limpa disponível.

Em vez disso, deve fazer as suas alterações num ramo de funcionalidade. Um ramo de funcionalidade tem um nome simples para identificar a alteração que fez. Por exemplo, se estiver a corrigir um bug que causa problemas de compilação no Windows 11, poderá criar um ramo de funcionalidade fix-win11-build. Se o seu bug estiver relacionado com um problema específico que foi reportado, também é comum fazer referência ao número do problema no nome do ramo (ex., fix-1234).

Para criar um ramo de funcionalidade fix-win11-build, execute:

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build
Reproduzir o problema

Reproduzir um problema

Não pode consertar um problema se não tiver o problema em primeiro lugar.Assim, reproduzir o problema é um pré-requisito para corrigi-lo. Em software, as situações irregulares são normalmente chamadas de "bugs", e os problemas são geralmente chamados de "relatórios de bugs".

Alguém forneceu um relatório de bug. Você precisa de validar se os passos descritas pelo relator estão a resultar no bug relatado. Pode reproduzir o mesmo resultado fazendo exatamente o que foi descrito no relatório? Se não conseguir, precisa descobrir o motivo.

Para começar a reprodução dum problema, vai precisar de configurar um [ambiente de desenvolvimento] .

Bugs no código

Numa situação ideal, terá a mesma configuração que a pessoa que relatou o bug, vai seguir os passos e conseguir reproduzir o bug conforme descrito. Em muitos casos, porém, isto não será tão simples. Muitos relatórios de bugs incluem apenas explicações vagas e um conjunto vago de condições. O problema é que muitos bugs variam de acordo com o conjunto de condições envolvidas, incluindo a forma de interação, várias condições prévias, sistema operativo, versão do sistema operativo, arquitetura da CPU ou se a máquina do utilizador é antiga e lenta ou nova e rápida. Quanto mais informações tivermos sobre a situação que envolve o bug, melhor. Tente reproduzir o conjunto de condições que o relator forneceu. Se não conseguir fazer isso, no seu próximo passo talvez precise de solicitar mais informações à pessoa que relatou o bug.

A melhor maneira de reproduzir um bug é com o menor exemplo possível que ainda exiba o problema. Na maioria das vezes, os relatores não fornecem um exemplo mínimo viável; se fornecerem algum exemplo, ele será copiado diretamente da sua aplicação do "mundo real". O seu objetivo será reduzir o relatório à forma mais simples possível que exiba o problema. O melhor caso de reprodução é o menor programa possível. Essa redução é útil porque determina qual é o problema real. Qualquer pessoa pode pegar no exemplo mínimo, executa-lo e observar o bug descrito.

Bugs na documentação

Os bugs na documentação podem se manifestar de diferentes maneiras. Há problemas de formatação que resultam em problemas de renderização. Às vezes, não se trata nem mesmo de um bug; a pessoa pode ter lido mal a documentação ou cometido um erro genuíno. Isso não significa necessariamente que não haja um problema com a documentação. O conteúdo pode ser pouco claro ou impreciso, dando margem a confusão ou má interpretação. É possível que um conceito que deveria ser discutido não o seja, porque não está completamente documentado.

Quando um bug é preenchido para um problema de documentação, vai querer verificar se o problema relatado ainda existe. No caso de problemas de renderização, vai precisar de criar a documentação para ver se consegue reproduzir o problema. Os problemas de conteúdo são uma questão de leitura para verificar se ninguém enviou uma atualização.

Atualizar o problema

O passo final do processo de triagem é documentar as suas descobertas deixando um comentário sobre o problema.

Se conseguir reproduzir o problema exatamente como descrito, isso é tudo o que precisa dizer. Deixe um comentário dizendo que confirmou que está a ver o mesmo problema, exatamente da maneira descrita pelo relator original.

Se puder fornecer algum contexto adicional, inclua os detalhes desse contexto. Isto pode incluir a possibilidade de reproduzir o problema num sistema operativo diferente, ou com uma versão diferente de algum dos softwares envolvidos, ou qualquer outra coisa que varie do relatório original.

Se o relatório original não continha detalhes necessários para reproduzi-lo, inclua esses detalhes. Isso pode incluir o fornecimento de detalhes do sistema operativo ou da versão que o relatório original não forneceu, relatórios ou rastreios de pilha mais completos ou instruções mais claras sobre a sequência exata de operações necessárias para reproduzir o problema. Se desenvolveu uma maneira mais simples de reproduzir o problema (ou se o relator original não forneceu um caso de reprodução), pode incluir detalhes desse método de reprodução.

Se não conseguir reproduzir o problema, deixe também um comentário detalhando o que tentou fazer. Saber onde um problema não existe é quase tão importante quanto saber onde ele existe, pois isso ajuda a restringir uma possível causa. Se tiver alguma teoria sobre porque não consegue reproduzir o problema — por exemplo, se acha que é um erro de utilização ou que o problema foi resolvido por uma atualização recente do sistema operativo — inclua essa especulação como parte do seu comentário.

Por fim, pode fazer recomendações para a equipa principal. Se acha que o relatório original está errado, sugira que o problema seja encerrado; se tiver uma teoria sobre a causa do problema, também pode sugerir isso. Os seus comentários vão ajudar a equipa principal a descobrir como passar o problema para o próximo passo.

Neste ponto, pode optar por tentar corrigir o problema que acabou de reproduzir; em alternativa, pode anotar suas descobertas e tentar reproduzir outro problema.

Se a correção do problema exigir alterações no código:

Escrever, executar e testar o código

Escrever, executar e testar código

Corrigir um bug ou implementar uma funcionalidade vai requerer escrever algum código novo.

Para começar a trabalhar em código, certifique-se de ter um ambiente de desenvolvimento configurado e de estar a trabalhar num ramo

Temos um guia de estilo de código que descreve as nossas diretrizes para escrever código para o BeeWare.

Desenvolvimento orientado por testes

Uma boa maneira de garantir que o seu código funciona conforme o esperado é, primeiro, escrever um caso de teste para verifica-lo. Esse caso de teste deve falhar inicialmente, já que o código que ele está a testar ainda não está presente. Pode então fazer as alterações necessárias no código para que o teste seja aprovado e ter a certeza de que o que escreveu está a resolver o problema que espera resolver.

Correr o seu código

Depois de escrever o código, é preciso garantir que ele funciona. Vai precisar executa-lo manualmente para verificar se ele está a fazer o que espera. Se ainda não o fez, é recomendável escrever um caso de teste para as alterações; conforme mencionado acima, esse teste deve falhar se o seu código estiver comentado ou ausente.

Vai adicionar o seu caso de teste ao conjunto de testes, para que ele possa ser executado junto com os outros testes. O próximo passo é executar o conjunto de testes.

Correr testes e cobertura

BeeWare utiliza tox para gerir o processo de testes e pytest para o seu próprio conjunto de testes.

O comando predefinido tox inclui a execução de:

  • ganchos de pré-submissão
  • Verificação das notas de lançamento do towncrier

  • verificação de conformidade da documentação

  • conjunto de testes para as versões disponíveis do Python

  • relatórios de cobertura de código

Isso é basicamente o que a CI executa quando envia um pedido de puxar.

Para executar o conjunto completo de testes, corra:

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

A execução do conjunto completo de testes pode demorar algum tempo. Pode acelerar consideravelmente o processo executando tox em paralelo, ao correr tox p (ou tox run-parallel). Ao executar o conjunto de testes emparalelo, vai receber menos retorno sobre a evolução dos testes durante a execução, mas mesmo assim vai obter um resumo de quaisquer problemas encontrados no final da execução. Deverá ver algum resultado a indicar que os testes foram executados. Pode ver testes SALTADOS, mas nunca deve receber resultados de teste FALHOU ou ERRO. Executamos o nosso conjunto completo de testes antes de fundir cada patch. Se esse processo detetar algum problema, não fundimos o patch. Se encontrar um erro ou falha no teste, ou há algo estranho no seu ambiente de teste, ou encontrou um caso extremo que não vimos antes — de qualquer forma, comunique-nos isso!

Além da aprovação dos testes, isto deve indicar 100% de cobertura de teste.

Executar variações de teste

Executar testes para várias versões do Python

Por predefinição, muitos dos comandos tox tentam executar o conjunto de testes várias vezes, uma vez para cada versão do Python compatível com o BeeWare. No entanto, para fazer isto, cada uma das versões do Python deve estar instalada no seu computador e disponível para o processo de deteção do Python do tox. Em geral, se uma versão do Python estiver disponível via PATH, então o tox deverá ser capaz de a encontrar e utilizar.

Executar apenas o conjunto de testes

Se estiver a iterar rapidamente uma nova funcionalidade, não precisa executar o conjunto completo de testes; pode executar apenas os testes de unidade. Para fazer isso, execute:

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

Executar um subconjunto de testes

Por predefinição, tox vai executar todos os testes do conjunto de testes de unidade. Ao desenvolver um novo teste, pode ser útil executar apenas esse teste específico. Para isso, pode passar qualquer especificador pytest como argumento para o tox. Estes caminhos de teste são relativos ao diretório briefcase. Por exemplo, para executar apenas os testes contidos num único ficheiro, execute:

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

Vai ainda receber um relatório de cobertura ao executar uma parte do conjunto de testes — mas os resultados de cobertura vão mostrar apenas as linhas de código que foram executadas pelos testes específicos que executou.

Executar o conjunto de testes para uma versão específica do Python

Por predefinição, tox -e py vai correr usando qualquer interpretador que resolver como python no seu computador. Se tiver várias versões do Python instaladas e quiser testar uma versão específica entre as que estão instaladas, é possível especificar a versão do Python a ser usada. Por exemplo, para executar o conjunto de testes no Python 3.10, execute:

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

Pode ser executado um subconjunto de testes ao adicionar -- e uma especificação de teste à linha de comando.

Executar o conjunto de testes sem cobertura (rápido)

Por predefinição, tox vai correr o conjunto de testes pytest no modo de única linha de execução. Pode acelerar a execução do conjunto de testes executando-o em paralelo. Esse modo não gera ficheiros de cobertura devido às complexidades envolvidas na captura de cobertura dentro dos processos criados. Para executar uma única versão do Python no modo "rápido", execute:

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

Pode ser executado um subconjunto de testes ao adicionar -- e uma especificação de teste à linha de comando; é possível usar uma versão específica do Python adicionando a versão ao destino do teste (por exemplo, py310-fast para executar rápido em Python 3.10).

Cobertura de código

BeeWare mantém 100% de cobertura de ramo no seu código-fonte. Ao adicionar ou modificar código no projeto, é necessário adicionar código de teste para garantir a cobertura de todas as alterações realizadas.

No entanto, BeeWare visa várias plataformas, bem como várias versões do Python, pelo que não é possível verificar a cobertura total numa única plataforma e versão do Python. Para contornar isso, várias regras de cobertura condicional são definidas na secção tool.coverage.coverage_conditional_plugin.rules do pyproject.toml (por exemplo, no-cover-if-is-windows pode ser usado para sinalizar um bloco de código que não será executado ao rodar o conjunto de testes no Windows). Essas regras são usadas para identificar secções de código que são cobertas apenas em plataformas ou versões específicas do Python.

De notar que a geração de relatórios de cobertura entre diferentes versões do Python pode apresentar algumas peculiaridades. Por exemplo, se os ficheiros de cobertura forem gerados usando uma versão do Python, mas a geração do relatório for feita noutra, o relatório poderá incluir falsos positivos para ramos não verificados. Por esse motivo, a geração de relatórios de cobertura deve sempre utilizar a versão mais antiga do Python usada para gerar os ficheiros de cobertura.

Compreender os resultados da cobertura

No final do resultado do teste de cobertura, deve haver um relatório com os dados de cobertura recolhidos:

Name    Stmts   Miss Branch BrPart   Cover   Missing
 ---------------------------------------------------
 TOTAL    7540      0   1040      0  100.0%

Isto indica-nos que o conjunto de testes executou todos os caminhos de ramo possíveis no código. Isto não é uma garantia de 100% de que não há bugs, mas significa que estamos a testar cada linha de código da base de código.

Se fizer alterações no código-fonte, é possível que surja uma lacuna nessa cobertura. Quando isso acontecer, o relatório de cobertura indicará quais linhas não estão a ser executadas. Por exemplo, digamos que fizemos uma alteração em some/interesting_file.py, adicionando uma nova lógica. O relatório de cobertura poderia ficar mais ou menos assim:

Name                                 Stmts   Miss Branch BrPart  Cover   Missing
 -------------------------------------------------------------------------------
 src/some/interesting_file.py           111      1     26      0  98.1%   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 TOTAL                                 7540      1   1726      0  99.9%

Isto diz-nos que a linha 170, as linhas 302 a 307 e um salto de ramo desde linha 320 para a linha 335 não estão a ser executados pelo conjunto de testes. Vai precisar adicionar novos testes (ou modificar um teste existente) para restaurar essa cobertura.

Relatório de cobertura para a plataforma anfitriã e a versão do Python

Pode gerar um relatório de cobertura para a sua plataforma e versão do Python. Por exemplo, para correr o conjunto de testes e gerar um relatório de cobertura no Python 3.10, execute:

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

Relatório de cobertura para a plataforma anfitriã

Se todas as versões suportadas do Python estiverem disponíveis para tox, a cobertura para a plataforma anfitriã pode ser reportada executando:

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

Relatórios de cobertura em HTML

Pode ser gerado um relatório de cobertura HTML acrescentando -html a qualquer um dos nomes de ambiente de cobertura tox, por exemplo:

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

Não se trata apenas de escrever testes!

Embora nos certificamos de testar todo o nosso código, a tarefa não se resume apenas a manter esse nível de testes. Parte da tarefa consiste em rever o código à medida que se avança. Podemos escrever um conjunto compreensível de testes para um colete salva-vidas de betão… mas um colete salva-vidas de betão continuava a ser inútil para o objetivo pretendido!

À medida que desenvolve testes, deve verificar se o módulo principal também é consistente internamente. Se notar algum nome de método que não seja internamente consistente (por exemplo, algo chamado on_select num módulo, mas chamado on_selected noutro), ou onde os dados não estejam sendo tratados de forma consistente, sinalize isso e nos informe criando um bilhete. Ou, se tiver certeza do que precisa ser feito, crie um pedido de puxar que corrija o problema que encontrou.

Depois de ter tudo a funcionar, pode submeter um pedido de puxar com as suas alterações.

Se a correção do problema exigir alterações na documentação:

Criar a documentação

Construir documentação

Antes de fazer qualquer alteração na documentação de BeeWare, é útil confirmar que pode compilar a documentação existente.

Antes de criar a documentação, e ter um [ambiente de desenvolvimento] configurado.

Você tem de ter um interpretador Python 3.13 instalado e disponível em seu caminho (isto é, python3.13 tem de iniciar um interpretador Python 3.13).

BeeWare usa o tox para criar a documentação. Os seguintes comandos tox têm de ser executados no mesmo local que o ficheiro tox.ini, que está no diretório raiz do projeto.

Antevisão da documentação em tempo real

Para suportar edição rápida da documentação, BeeWare tem um modo de "antevisão em tempo real".

A pré-visualização em tempo real vai compilar com avisos!

O serviço em tempo real está disponível para iteração nas suas atualizações de documentação. Enquanto estiver no processo de atualizar coisas, pode introduzir um problema de marcação. Os problemas considerados WARNING farão com que uma compilação standard falhe; no entanto, o serviço em tempo real está configurado para indicar avisos na saída da consola, enquanto continua a compilar. Isto permite que faça iterações sem precisar reiniciar a antevisão em tempo real.

Um WARNING é diferente de um ERROR. Se introduzir um problema que seja considerado um ERROR, o serviço em tempo real vai falhar e precisar de ser reiniciado. Ele não será iniciado novamente até que o problema WARNING esteja resolvido.

Para iniciar o servidor de tempo real:

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

Isto vai compilar a documentação, iniciar um servidor Web para servir a documentação, e observar o sistema de ficheiros em busca de alterações na fonte da documentação.

Após o servidor ter arrancado, vai ver algo parecido com o seguinte na saída da consola:

INFORMAÇÃO    -  [11:18:51] A servir em http://127.0.0.1:8000/

Abra um navegador e navegue até ao URL fornecido. Agora pode começar a iteração na documentação. Se uma alteração for detetada, a documentação será recompilada e qualquer navegador que estiver a visualizar a página modificada será atualizado automaticamente.

O docs-live é um passo inicial

A execução do docs-live para trabalhar com o servidor ativo destina-se a iteração inicial. Você deve sempre executar uma compilação local antes de enviar um pedido de puxar.

Compilação local

Quando terminar a iteração, vai precisar fazer uma compilação local da documentação. Este processo de compilação foi desenhado para falhar se houver algum problema de marcação. Isso permite-lhe capturar qualquer coisa que possa ter passado despercebida com o servidor em tempo real.

Gerar uma compilação local

Para gerar uma compilação local:

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

O resultado desta compilação vai estar no diretório _build na raiz do projeto.

Gerar uma compilação local traduzida

A documentação de BeeWare está traduzida em vários idiomas. As atualizações na documentação em Inglês têm o potencial de provocar problemas nas compilações dos outros idiomas. É importante verificar se todas as compilações estão a funcionar antes de submeter um pedido de puxar.

Para gerar uma compilação de todas as traduções disponíveis:

(venv) $ tox -e docs-all

(venv) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

O resultado de cada compilação de idioma vai estar no diretório _build/html/<languagecode> associado, onde <languagecode> é o código de idioma de dois ou cinco caracteres associado ao idioma específico (ex., fr para Francês, it para Italiano, etc.).

Se encontrar um problema com uma única compilação, poderá executar essa compilação individual em separado, executando tox -e docs-<languagecode>. Por exemplo, para compilar somente a documentação em Francês, execute:

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

O resultado de uma compilação num único idioma vai estar no diretório _build.

Análise sintática da documentação

O processo de compilação vai identificar problemas de Markdown, mas BeeWare realiza algumas verificações adicionais de estilo e formatação, análises sintáticas conhecidas como "linting". Para executar as verificações de linting:

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

Isso vai validar que a documentação não contém:

  • hiperligações mortas
  • palavras com erros ortográficos

Se uma ortografia válida de uma palavra for identificada como incorreta, adicione a palavra à lista em docs/spelling_wordlist. Isto vai adicionar a palavra ao dicionário do corretor ortográfico. Ao adicionar palavras a essa lista, lembre-se:

  • Preferimos a ortografia dos EUA, com algumas liberdades para o coloquial específico da programação (ex., "apps") e a verbalização de substantivos (ex., "scrollable")
  • Qualquer referência a um nome de um produto deve usar a capitalização preferencial do produto. (por exemplo, "macOS", "GTK", "pytest", "Pygame", "PyScript").
  • Se um termo estiver a ser usado "como código", ele deverá ser citado como literal (assim) em vez de ser adicionado ao dicionário.

Depois de criar os documentos com sucesso, vai estar pronto para escrever a documentação.

Escrever documentação

Escrever documentação

Estes são os passos a seguir para escrever sua contribuição de documentação para BeeWare.

Antes de começar a escrever a documentação, certifique-se de que é capaz de compilar a documentação e que está a trabalhar num ramo.

Atualizar a documentação existente

Se estiver a editar os documentos existentes, será necessário localizar o ficheiro no diretório /docs/en. A estrutura do ficheiro segue a estrutura da página, assim pode localizar o ficheiro usando o URL da documentação.

Adicionar nova documentação

Se estiver a adicionar um novo documento, há mais alguns passos envolvidos.

Vai precisar criar o documento no local apropriado dentro do diretório docs/en. Para fins de discussão, digamos que esteja a adicionar um novo documento com o nome de ficheiro new_doc.md.

Depois, vai precisar atualizar o ficheiro docs/en/SUMMARY.md para incluir o novo ficheiro. O SUMMARY.md é organizado para refletir basicamente a estrutura do diretório docs/en, mas, o que é mais importante, determina diretamente a estrutura da barra lateral esquerda. Se localizar a secção onde pretende incluir o new_doc.md, não vai precisar alterar nada no SUMMARY.md caso veja um caminho com wildcard listado. Por exemplo:

- ./caminho/para/diretório/*

Se a secção em que pretende incluir new_doc.md for uma lista de atalhos Markdown individuais, será necessário adicionar um atalho explícito para o seu. Por exemplo:

- [Meu novo documento](new_doc.md)

Escrever a sua documentação

Agora pode abrir o ficheiro desejado no seu editor, e começar a escrever.

Temos um guia de estilo de documentação que descreve as nossas diretrizes para escrever documentação para o BeeWare.

Quando estiver satisfeito com a sua nova documentação, pode submeter um pedido de puxar com as suas alterações propostas.

Quando estiver pronto para submeter a sua contribuição:

Adicionar uma nota de alteração

Adicionar informações de alterações para as notas de lançamento

Muitas ferramentas do BeeWare utilizam o towncrier para auxiliar na criação das notas de lançamento de cada versão. Quando envia um pedido de puxar para uma das ferramentas aplicáveis, ele precisa de incluir uma nota de alteração - esta nota de alteração vai se tornar na entrada nas notas de lançamento que descrevem a alteração que foi feita.

Todo o pedido de puxar deve incluir pelo menos um ficheiro no diretório changes/ que forneça uma breve descrição da alteração implementada pelo pedido de puxar. A nota de alteração deve estar no formato Markdown, num ficheiro que tenha o nome no formato <id>.<fragment type>.md. Se a alteração que está a propor for corrigir um bug ou implementar uma funcionalidade para o qual há um número de problema existente, o ID deverá ser o número desse bilhete. Se a alteração não tiver um problema correspondente, o número do PR poderá ser usado como ID. Você não vai saber o número do PR até que envie o pedido, portanto, a primeira passagem do CI vai falhar na verificação do towncrier; adicione a nota de alteração e envie uma atualização do PR e o CI deverá ser aprovado.

Há cinco tipos de fragmentos:

  • feature: O PR adiciona um novo comportamento ou capacidade que não era possível anteriormente (ex., adicionar suporte a um novo formato de empacotamento ou uma nova funcionalidade num formato de empacotamento existente);
  • bugfix: O PR corrige um bug na implementação existente;
  • doc: O PR é uma melhoria significativa na documentação;
  • removal; O PR representa uma alteração incompatível com versões anteriores na API BeeWare API; ou
  • misc; Uma alteração menor ou administrativa (ex., correção de um erro de ortográfico, um esclarecimento menor de linguagem ou atualização de uma versão de dependência) que não precisa ser anunciada nas notas de lançamento.

Essa descrição na nota de alteração deve ser um resumo de "publicidade" de alto nível da alteração sob a perspetiva do utilizador, e não uma descrição técnica profunda ou detalhes de implementação. Ela é diferente de uma mensagem de submissão - uma mensagem de submissão descreve o que foi feito para que os futuros desenvolvedores possam acompanhar o raciocínio de uma alteração; a nota de alteração é uma descrição para o benefício dos utilizadores, que podem não ter conhecimento dos aspetos internos.

Por exemplo, se corrigir um bug relacionado com a nomenclatura do projeto, a mensagem de submissão poderá ser a seguinte:

Aplicar uma verificação de expressão regular mais forte para não permitir nomes de projetos que comecem com dígitos.

A nota de alteração correspondente seria algo como:

Os nomes dos projetos não podem mais começar com um número.

Alguns PRs vão introduzir várias funcionalidades e corrigir vários bugs, ou introduzir várias alterações incompatíveis com versões anteriores. Neste caso, o PR pode ter vários ficheiros de notas de alteração. Se precisar associar dois tipos de fragmentos à mesma ID, poderá acrescentar um sufixo numérico. Por exemplo, se o PR 789 adicionou uma funcionalidade descrita pelo bilhete 123, fechou um bug descrito pelo bilhete 234 e também fez duas alterações incompatíveis com versões anteriores, pode ter 4 ficheiros de notas de alteração:

  • 123.feature.md
  • 234.bugfix.md
  • 789.removal.1.md
  • 789.removal.2.md

Para mais informações sobre o towncrier e os tipos de fragmentos, consulte News Fragments. Também pode ver exemplos existentes de fragmentos de notícias no diretório changes do repositório BeeWare. Se essa pasta estiver vazia, provavelmente é porque BeeWare publicou recentemente uma nova versão; os ficheiros de notas de alteração são excluídos e combinados para atualizar as notas de lançamento com cada versão. Pode consultar esse ficheiro para ver o estilo de comentário necessário; pode consultar PRs recentemente fundidos para ver como formatar as suas notas de alteração.

Submeter um pedido de puxar

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.