Ir para o conteúdo

Corrigindo um problema

BeeWare rastreia uma lista de [problemas conhecidos] (https://github.com/search?q=org%3Abeeware%20is%3Aopen%20is%3Aissue%20label%3Abug&type=issues). Qualquer um desses problemas é candidato a ser trabalhado.

Essa lista pode ser filtrada de várias maneiras. Por exemplo, você pode filtrar por plataforma, para que possa se concentrar nos problemas que afetam as plataformas em que você pode testar; ou pode filtrar por tipo de problema, como documentation bugs. Há também um filtro para [boas primeiras edições] (https://github.com/search?q=org%3Abeeware+is%3Aopen+is%3Aissue+label%3Abug+label%3A%22good+first+issue%22&type=issues) - esses 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 em 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 você pode reproduzir o problema. Use as informações fornecidas no relatório de bug para tentar reproduzir o problema. Se você não conseguir reproduzir o problema, informe o que encontrou como um comentário sobre o problema e escolha outro problema.

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

Mesmo que você 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 você 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 (um pequeno aplicativo de amostra que não faz nada além de reproduzir o problema), fornecer um pode ser de grande ajuda.

Contribuindo com uma correção de problema

Configurar um ambiente de desenvolvimento

A contribuição para BeeWare exige que você configure um ambiente de desenvolvimento.

Pré-requisitos

Você precisará instalar os seguintes pré-requisitos.

BeeWare requer Python 3.10+. Você também precisará de um método para gerenciar ambientes virtuais (como o venv).

Para verificar a versão do Python que você instalou, execute:

Python 3.8.10 (padrão, 20 de julho de 2020, 16:16:00)

Se você tiver mais de uma versão do Python instalada, talvez seja necessário substituir python3 por um número de versão específico (por exemplo, python3.13)

Recomendamos evitar versões do Python lançadas recentemente (ou seja, versões que tenham um micro-número de versão ".0" ou ".1", como, por exemplo, 3.14.0). Isso ocorre porque as ferramentas necessárias para dar suporte ao Python no macOS geralmente ficam defasadas e não estão disponíveis para as versões estáveis do Python lançadas recentemente.

BeeWare requer Python 3.10+. Você também precisará de um método para gerenciar ambientes virtuais (como o venv).

Para verificar a versão do Python que você instalou, execute:

Python 3.8.10 (padrão, 20 de julho de 2020, 16:16:00)

Se você tiver mais de uma versão do Python instalada, talvez seja necessário substituir python3 por um número de versão específico (por exemplo, python3.13)

Recomendamos evitar versões do Python lançadas recentemente (ou seja, versões que tenham um micro número de versão ".0" ou ".1", como, por exemplo, 3.14.0). Isso ocorre porque as ferramentas necessárias para dar suporte ao Python no Linux geralmente ficam defasadas e não estão disponíveis para as versões estáveis do Python lançadas recentemente.

BeeWare requer Python 3.10+. Você também precisará de um método para gerenciar ambientes virtuais (como o venv).

Para verificar a versão do Python que você instalou, execute:

C:\...>py -3 --version

Se você tiver mais de uma versão do Python instalada, talvez seja necessário substituir o -3 por um número de versão específico (por exemplo, -python3.13)

Recomendamos evitar versões do Python lançadas recentemente (ou seja, versões que tenham um micro número de versão ".0" ou ".1", como, por exemplo, 3.14.0). Isso ocorre porque as ferramentas necessárias para dar suporte ao Python no Windows geralmente ficam defasadas e não estão disponíveis para as versões estáveis do Python lançadas recentemente.

Configure seu ambiente de desenvolvimento

A maneira recomendada de configurar seu ambiente de desenvolvimento para BeeWare é usar um ambiente virtual e, em seguida, instalar a versão de desenvolvimento de BeeWare e suas dependências.

Clonar o repositório BeeWare

Em seguida, vá para a página BeeWare no GitHub e, se ainda não o fez, bifurque o repositório em sua própria conta. Em seguida, clique no botão "<> Code" em sua bifurcação. Se você tiver o aplicativo de desktop GitHub instalado no seu computador, poderá selecionar "Open with GitHub Desktop"; caso contrário, copie a URL HTTPS fornecida e use-a para clonar o repositório no seu computador usando a linha de comando:

Faça um fork do repositório BeeWare e, em seguida:

$ git clone https://github.com/<seu nome de usuário>/beeware.git

(substituindo seu nome de usuário do GitHub)

Faça um fork do repositório BeeWare e, em seguida:

$ git clone https://github.com/<seu nome de usuário>/beeware.git

(substituindo seu nome de usuário do GitHub)

Faça um fork do repositório BeeWare e, em seguida:

C:\...>git clone https://github.com/<seu nome de usuário>/beeware.git

(substituindo seu nome de usuário do GitHub)

Definir um repositório upstream

Após clonar seu fork, adicione o repositório BeeWare como um upstream remoto. Isso fornece ao seu clone local uma referência ao repositório original, facilitando a sincronização de atualizações ao longo do tempo.

Você também precisará de tags de upstream para que ferramentas como Toga e Briefcase possam resolver números de versão precisos:

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

C:\...>git remote add upstream https://github.com/beeware/beeware.git
C:\...>git fetch --tags upstream

Se você quiser que seu fork também inclua essas tags, você pode enviá-las:

$ git push --tags

Isso pode ser útil se você criar um novo clone posteriormente e quiser que as tags estejam disponíveis em seu fork.

Criar um ambiente virtual

Para configurar um ambiente virtual e atualizar o pip, execute:

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

Seu prompt agora deve ter um prefixo (.venv) na frente.

Instalar BeeWare

Agora que você tem o código-fonte, pode fazer uma instalação editável de BeeWare em seu ambiente de desenvolvimento. Execute o seguinte comando:

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

Ativar o pré-compromisso

BeeWare usa uma ferramenta chamada pre-commit para identificar problemas simples e padronizar a formatação do código. Ele faz isso instalando um gancho do git que executa automaticamente uma série de linters de código antes de finalizar qualquer commit do git. Para ativar o pre-commit, execute:

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

Agora você está pronto para começar a hackear o BeeWare!

Trabalhar a partir de uma filial

Antes de começar a trabalhar em sua alteração, certifique-se de ter criado uma ramificação. Por padrão, quando você clona a bifurcação do seu repositório, o check-out é feito na ramificação main. Essa é uma cópia direta da ramificação main de BeeWare.

Embora você possa enviar uma pull request do seu branch main, é preferível que você não faça isso. Se você enviar uma pull request que esteja quase correta, o membro da equipe principal que revisar a pull request poderá fazer as alterações necessárias, em vez de fornecer feedback solicitando uma pequena alteração. No entanto, se você enviar a pull request do branch main, os revisores serão impedidos de fazer modificações.

Trabalhar no branch principal também dificulta para você depois de concluir o primeiro pull request. Se quiser trabalhar em um segundo pull request, você precisará ter uma cópia "limpa" do branch principal do projeto upstream no qual basear sua segunda contribuição; se você fez sua primeira contribuição a partir do branch principal, não terá mais essa versão limpa disponível.

Em vez disso, você deve fazer suas alterações em um feature branch. Uma ramificação de recurso tem um nome simples para identificar a alteração que você fez. Por exemplo, se você estiver corrigindo um bug que causa problemas de compilação no Windows 11, poderá criar uma ramificação de recurso fix-win11-build. Se o bug estiver relacionado a um problema específico que tenha sido relatado, também é comum fazer referência ao número do problema no nome do branch (por exemplo, fix-1234).

Para criar uma ramificação de recurso 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
Reproduza o problema

Você não pode consertar um problema se não tiver o problema em primeiro lugar. Portanto, reproduzir o problema é um pré-requisito para corrigi-lo. Em software, os problemas são comumente chamados de "bugs", e os problemas são geralmente chamados de "relatórios de bugs".

Alguém forneceu um relatório de bug. Você precisa validar se as etapas descritas pelo relator estão resultando no bug relatado. Você pode reproduzir o mesmo resultado fazendo exatamente o que foi descrito no relatório? Se não conseguir, você precisa descobrir o motivo.

Bugs no código

Em uma situação ideal, você terá a mesma configuração que a pessoa que relatou o bug, seguirá as etapas e conseguirá reproduzir o bug conforme descrito. Em muitos casos, porém, isso 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 operacional, versão do sistema operacional, arquitetura da CPU ou se a máquina do usuário é 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, sua próxima etapa talvez precise 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 fornecerão um exemplo mínimo viável; se fornecerem algum exemplo, ele será copiado diretamente de seu aplicativo do "mundo real". 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 o exemplo mínimo, executá-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 é registrado para um problema de documentação, você deve verificar se o problema relatado ainda existe. No caso de problemas de renderização, você precisará 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

A etapa final do processo de triagem é documentar suas descobertas deixando um comentário sobre o problema.

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

Se você puder fornecer algum contexto adicional, inclua os detalhes desse contexto. Isso pode incluir a possibilidade de reproduzir o problema em um sistema operacional 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 operacional ou da versão que o relatório original não forneceu, logs ou rastreamentos de pilha mais completos ou instruções mais claras sobre a sequência exata de operações necessárias para reproduzir o problema. Se você desenvolveu uma maneira mais simples de reproduzir o problema (ou se o relator original não forneceu um caso de reprodução), você pode incluir detalhes dessa metodologia de reprodução.

Se você não conseguir reproduzir o problema, deixe também um comentário detalhando o que você 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 você tiver alguma teoria sobre por que não consegue reproduzir o problema — por exemplo, se você acha que é um erro de uso ou que o problema foi resolvido por uma atualização recente do sistema operacional — inclua essa especulação como parte do seu comentário.

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

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

Escreva, execute e teste o código

Para corrigir um bug ou implementar um recurso, será necessário escrever um novo código.

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

Desenvolvimento orientado por testes

Uma boa maneira de garantir que seu código funcione conforme o esperado é, primeiro, escrever um caso de teste para verificá-lo. Esse caso de teste deve falhar inicialmente, já que o código que ele está testando ainda não está presente. Você 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á resolvendo o problema que esperava resolver.

Execute seu código

Depois de escrever o código, é preciso garantir que ele funcione. Você precisará executá-lo manualmente para verificar se ele está fazendo o que você 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 código estiver comentado ou ausente.

Você adicionará 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.

Executando testes e cobertura

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

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

  • ganchos de pré-confirmação
  • Verificação das notas de lançamento

  • 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 você envia uma solicitação de pull.

Para executar o conjunto completo de testes, digite:

(.venv) $ tox

(.venv) $ tox

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

A execução do conjunto completo de testes pode demorar algum tempo. Você pode acelerar consideravelmente o processo executando tox em paralelo, ou seja, executando tox p (ou tox run-parallel). Ao executar o conjunto de testes em paralelo, você receberá menos feedback sobre o andamento dos testes durante a execução, mas ainda assim obterá um resumo de quaisquer problemas encontrados ao final da execução. Você deverá ver alguma saída indicando que os testes foram executados. Você pode ver SKIPPED testes, mas nunca deve receber resultados de teste FAIL ou ERROR. Executamos nosso conjunto completo de testes antes de mesclar cada patch. Se esse processo detectar algum problema, não mesclamos o patch. Se você encontrar um erro ou falha no teste, ou há algo estranho em seu ambiente de teste, ou você encontrou um caso extremo que não vimos antes — de qualquer forma, nos avise!

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

Executando variações de teste

Executar testes em várias versões do Python

Por padrão, muitos dos comandos tox tentarão executar o conjunto de testes várias vezes, uma vez para cada versão do Python compatível com o BeeWare. Para isso, porém, cada uma das versões do Python deve estar instalada em seu computador e disponível para o processo de [detecção]tox do Python do (https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery). Em geral, se uma versão do Python estiver disponível via PATH, então o tox deverá ser capaz de encontrá-la e utilizá-la.

Execute apenas o conjunto de testes

Se você estiver fazendo iterações rápidas em um novo recurso, não precisa executar o conjunto completo de testes; você pode executar apenas os testes unitários. Para fazer isso, execute:

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Executar um subconjunto de testes

Por padrão, tox executa todos os testes do conjunto de testes unitários. Ao desenvolver um novo teste, pode ser útil executar apenas esse teste específico. Para isso, você pode passar qualquer especificador pytest como argumento para tox. Esses caminhos de teste são relativos ao diretório briefcase. Por exemplo, para executar apenas os testes contidos em um único arquivo, 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

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

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

Por padrão, tox -e py será executado usando o interpretador que for identificado como python no seu computador. Se você 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

É possível executar um subconjunto de testes adicionando -- e uma especificação de teste à linha de comando.

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

Por padrão, tox executará o conjunto de testes pytest no modo de thread único. É possível acelerar a execução do conjunto de testes executando-o em paralelo. Esse modo não gera arquivos 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

É possível executar um subconjunto de testes adicionando -- 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 o fast no Python 3.10).

Cobertura de código

BeeWare mantém 100% de cobertura de ramificação em 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 é compatível com várias plataformas, bem como com várias versões do Python, pelo que não é possível verificar a cobertura total em uma única plataforma e versão do Python. Para contornar isso, várias regras de cobertura condicional são definidas na seçã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 seções de código que são cobertas apenas em plataformas ou versões específicas do Python.

É importante notar que a geração de relatórios de cobertura entre diferentes versões do Python pode apresentar algumas peculiaridades. Por exemplo, se os arquivos de cobertura forem gerados usando uma versão do Python, mas a geração do relatório for feita em outra, o relatório poderá incluir falsos positivos para ramificações não verificadas. 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 arquivos de cobertura.

Entendendo os resultados da cobertura

No final da saída do teste de cobertura, deve haver um relatório com os dados de cobertura coletados:

Nome    Extratos   Filial ausente   Parte da conta   Cobertura   Ausente
 ---------------------------------------------------
 TOTAL    7540 0   1040 0  100,0%

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

Se você 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 sendo executadas. Por exemplo, digamos que tenhamos feito uma alteração em some/interesting_file.py, adicionando uma nova lógica. O relatório de cobertura poderia ficar mais ou menos assim:

Nome Instruções   Erros de ramificação BrPart  Cobertura   Ausências
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98,1%   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 TOTAL 7540 1   1726 0  99,9%

Isso indica que a linha 170, as linhas 302 a 307 e um salto de execução da linha 320 para a linha 335 não estão sendo executados pelo conjunto de testes. Você precisará adicionar novos testes (ou modificar um teste existente) para restaurar essa cobertura.

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

Você pode gerar um relatório de cobertura para a sua plataforma e versão do Python. Por exemplo, para executar 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 de hospedagem

Se todas as versões compatíveis do Python estiverem disponíveis para tox, a cobertura para a plataforma hospedeira pode ser gerada 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

É possível gerar 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 certifiquemos 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 revisar o código à medida que se avança. Você poderia escrever um conjunto abrangente de testes para um colete salva-vidas de concreto… mas um colete salva-vidas de concreto continuaria sendo inútil para o fim a que se destina!

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

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

Criar documentação

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

Você deve ter um interpretador Python 3.13 instalado e disponível em seu caminho (ou seja, python3.13 deve iniciar um interpretador Python 3.13).

BeeWare utiliza o tox para criar a documentação. Os comandos tox a seguir devem ser executados no mesmo local que o arquivo tox.ini, que está no diretório raiz do projeto.

Visualização da documentação em tempo real

Para dar suporte à edição rápida da documentação, BeeWare tem um modo de "visualização ao vivo".

A pré-visualização ao vivo será criada com avisos!

O serviço ao vivo está disponível para iterar em suas atualizações de documentação. Enquanto estiver no processo de atualização, você poderá introduzir um problema de marcação. Os problemas considerados WARNING farão com que uma compilação padrão falhe; no entanto, o serviço ao vivo está configurado para indicar avisos na saída do console, enquanto continua a compilação. Isso permite que você faça iterações sem precisar reiniciar a visualização ao vivo.

Um WARNING é diferente de um ERROR. Se você introduzir um problema que seja considerado um ERROR, o serviço ao vivo falhará e precisará ser reiniciado. Ele não será iniciado novamente até que o problema WARNING seja resolvido.

Para iniciar o servidor ativo:

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

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

Isso criará a documentação, iniciará um servidor da Web para servir a documentação e observará o sistema de arquivos em busca de alterações na fonte da documentação.

Quando o servidor for iniciado, você verá algo parecido com o seguinte na saída do console:

INFORMAÇÕES    -  [11:18:51] Servindo em http://127.0.0.1:8000/

Abra um navegador e navegue até o URL fornecido. Agora você pode começar a iterar na documentação. Se uma alteração for detectada, a documentação será reconstruída e qualquer navegador que estiver visualizando a página modificada será atualizado automaticamente.

O docs-live é uma etapa inicial

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

Construção local

Quando terminar a iteração, você precisará fazer uma compilação local da documentação. Esse processo de compilação foi projetado para falhar se houver algum problema de marcação. Isso permite que você capture qualquer coisa que possa ter passado despercebida no servidor ativo.

Geração de 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 dessa compilação estará no diretório _build na raiz do projeto.

Geração de uma compilação local traduzida

A documentação da BeeWare está traduzida em vários idiomas. As atualizações na documentação em inglês podem levar a problemas nas compilações em outros idiomas. É importante verificar se todas as compilações estão funcionando antes de enviar uma solicitação pull.

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

(verbo) $ tox -e docs-all

(verbo) $ tox -e docs-all

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

A saída de cada compilação de idioma estará no diretório _build/html/<languagecode> associado, em que <languagecode> é o código de idioma de dois ou cinco caracteres associado ao idioma específico (por exemplo, fr para francês, it para italiano etc.).

Se você encontrar um problema com uma única compilação, poderá executar essa compilação individual separadamente, 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

A saída de uma compilação em um único idioma estará no diretório _build.

Linting de documentação

O processo de compilação identificará problemas de Markdown, mas BeeWare realiza algumas verificações adicionais de estilo e formatação, 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 validará que a documentação não contém:

  • hiperlinks mortos
  • 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. Isso 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 coloquialismo específico da programação (por exemplo, "apps") e a verbalização de substantivos (por exemplo, "scrollable")
  • Qualquer referência ao nome de um produto deve usar a capitalização preferencial do produto. (por exemplo, "macOS", "GTK", "pytest", "Pygame", "PyScript").
  • Se um termo estiver sendo usado "como código", ele deverá ser citado como um literal (como este) em vez de ser adicionado ao dicionário.
Escrever documentação

Estas são as etapas a serem seguidas para escrever sua contribuição de documentação para BeeWare.

Atualização da documentação existente

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

Adição de nova documentação

Se você estiver adicionando um novo documento, há mais algumas etapas envolvidas.

Você precisará criar o documento no local apropriado dentro do diretório docs/en. Para fins de discussão, digamos que você esteja adicionando um novo documento com o nome de arquivo new_doc.md.

Em seguida, você precisará atualizar o arquivo docs/en/SUMMARY.md para incluir o novo arquivo. 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 você localizar a seção onde pretende incluir o new_doc.md, não precisará alterar nada no SUMMARY.md caso veja um caminho curinga listado. Por exemplo:

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

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

- [Meu novo documento](new_doc.md)

Escrevendo sua documentação

Agora você pode abrir o arquivo desejado em seu editor e começar a escrever.

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

Quando você estiver pronto para enviar sua contribuição:

Adicionar uma nota de alteração

Muitas ferramentas do BeeWare utilizam o towncrier para auxiliar na criação das notas de lançamento de cada versão. Quando você envia uma pull request para uma das ferramentas aplicáveis, ela precisa incluir uma change note (nota de alteração) - essa nota de alteração se tornará a entrada nas notas de versão que descrevem a alteração que foi feita.

Todo pull request deve incluir pelo menos um arquivo no diretório changes/ que forneça uma breve descrição da alteração implementada pelo pull request. A nota de alteração deve estar no formato Markdown, em um arquivo que tenha o nome no formato <id>.<fragment type>.md. Se a alteração que você está propondo corrigir um bug ou implementar um recurso para o qual há um número de problema existente, o ID será o número desse tíquete. Se a alteração não tiver um problema correspondente, o número do PR poderá ser usado como ID. Você não saberá o número do PR até que envie o pull request, portanto, a primeira passagem do CI 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 (recurso): O PR adiciona um novo comportamento ou recurso que não era possível anteriormente (por exemplo, adicionar suporte a um novo formato de empacotamento ou um novo recurso em um 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 (por exemplo, correção de um erro de digitação, um esclarecimento de linguagem menor ou atualização de uma versão de dependência) que não precisa ser anunciada nas notas da versão.

Essa descrição na nota de alteração deve ser um resumo de "marketing" de alto nível da alteração sob a perspectiva do usuário, e não uma descrição técnica profunda ou detalhes de implementação. Ela é diferente de uma mensagem de confirmação - uma mensagem de confirmaçã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 usuários, que podem não ter conhecimento dos aspectos internos.

Por exemplo, se você corrigir um bug relacionado à nomenclatura do projeto, a mensagem de confirmação poderá ser a seguinte:

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

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

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

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

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

Para obter mais informações sobre o towncrier e os tipos de fragmentos, consulte News Fragments. Você 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 arquivos de notas de alteração são excluídos e combinados para atualizar as notas de versão a cada versão. Você pode consultar esse arquivo para ver o estilo de comentário necessário; você pode consultar recently merged PRs para ver como formatar suas notas de alteração.

Envie uma solicitação pull

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

Trabalhar com pre-commit

Quando você confirma qualquer alteração, o pre-commit é executado automaticamente. Se houver algum problema encontrado com o commit, isso fará com que o commit falhe. Sempre que possível, o pre-commit 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..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

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..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

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..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

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

Nesse caso, o ruff corrigiu automaticamente o problema; portanto, você pode adicionar novamente todos os arquivos que foram modificados como resultado das verificações de pré-compromisso e confirmar novamente a alteração. Entretanto, algumas verificações exigirão que você faça modificações manuais. Depois de fazer essas alterações, adicione novamente os arquivos modificados e faça o commit 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 file changed, 4 insertions(+), 2 deletions(-)

(.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 file changed, 4 insertions(+), 2 deletions(-)

(.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 file changed, 4 insertions(+), 2 deletions(-)

Quando tudo for aprovado, você verá uma mensagem indicando que o commit foi finalizado, e o registro do git mostrará o commit como a adição mais recente. Agora você está pronto para fazer push para o GitHub.

Envie suas alterações para o GitHub e crie sua solicitação pull

Na primeira vez que fizer push para o GitHub, você receberá uma URL que o levará diretamente à página do GitHub para criar uma nova pull request. Siga a URL e crie sua pull request.

A seguir, 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 você já tiver feito push do branch atual para o GitHub, não receberá o URL novamente. No entanto, há outras maneiras de acessar a URL de criação de PR:

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

Qualquer uma dessas opções permitirá que você crie seu novo pull request.

A CLI do GitHub: gh

O GitHub fornece a GitHub CLI, 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 abrange todos os recursos.

Conteúdo da solicitação pull

O título de uma pull request deve ser informativo, claro e conciso. Tente mantê-lo curto, se possível, mas títulos mais longos são aceitáveis, se necessário. Um bom título de PR deve dar a uma pessoa sem nenhum contexto uma ideia razoavelmente sólida do bug ou do recurso implementado pelo seu PR.

A descrição do PR deve refletir claramente as alterações no PR. Uma pessoa sem qualquer contexto deve ser capaz de ler sua descrição e obter uma compreensão relativamente completa do motivo pelo qual a alteração está sendo feita. Evite piadas, expressões idiomáticas, coloquialismos 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á acontecendo 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 você tenha usado e que ainda não faça parte das alterações presentes no PR, eles deverão ser explicados e incluídos no PR. A explicação deve incluir como executá-los e o que fazer para reproduzir o resultado desejado.

Se a sua pull request for resolver o problema nº 1234, você deverá incluir o texto Correções nº 1234 na descrição da pull request. Isso fará com que o problema seja fechado automaticamente quando o pull request for mesclado. Você pode fazer referência a outras discussões, problemas ou pull requests usando a mesma sintaxe #1234. Você pode se referir a um problema em um repositório diferente prefixando o número com - por exemplo, python/cpython#1234 se referiria ao problema 1234 no repositório CPython.

Integração contínua

Integração contínua, ou CI, é o processo de executar verificações automatizadas em seu pull request. 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 revisaremos um PR que não esteja sendo aprovado na CI. Se você criar uma solicitação pull e a CI falhar, não iniciaremos sua análise até que ela seja aprovada. Se suas alterações resultarem em uma falha, é sua responsabilidade investigar o motivo e resolver o problema.

Quando o CI falhar, os links de falha serão exibidos na parte inferior da página PR, sob o título "Algumas verificações não foram bem-sucedidas". Você 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 você clicar no link de falha, será levado ao registro. O registro geralmente fornece todas as informações necessárias para descobrir o que causou a falha. Leia o registro e tente descobrir por que a falha está ocorrendo e, em seguida, faça o que for necessário para resolvê-la.

Ocasionalmente, uma verificação de CI 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 você 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, você precisa enviar novas alterações para sua ramificação.

Se você se encontrar em uma situação em que precisa de ajuda para fazer com que o CI seja aprovado, deixe um comentário no RP nos informando e faremos o possível para ajudar.

As verificações pre-commit e towncrier

Se as verificações pre-commit ou towncrier falharem, isso impedirá a execução da maioria das demais verificações de CI. Você 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 você fizer push para a ramificação, a CI será iniciada. Se você for fazer várias alterações, é melhor fazer essas alterações localmente e enviá-las todas de uma vez. O CI só será executado no commit mais recente em um lote, minimizando a carga em nosso sistema de CI.

O processo de envio de sua RP não é concluído até que ela seja aprovada pelo CI ou até que você forneça uma explicação do motivo pelo qual ela não foi aprovada.