Ir para o conteúdo

Implementação de um novo recurso

Após a conclusão do processo de proposta, você deverá ter um design completo para um novo recurso. Isso significa que é hora de começar a escrever!

Se o seu recurso exigir uma implementação específica da plataforma, o processo de proposta deverá ter validado que a ideia poderia ser implementada em todas as plataformas. No entanto, como a pessoa que implementa um novo recurso pela primeira vez, você não é responsável por implementar o novo recurso em todas as plataformas. Você precisa fornecer uma implementação completa para pelo menos uma plataforma, incluindo testes. Para todas as outras plataformas, você precisará fornecer uma implementação "stub", ou seja, uma implementação que forneça a definição da interface simples, mas que gere um NotImplementedError ou envie uma mensagem de registro informando que o comportamento não está implementado naquela plataforma.

Uma parte importante da implementação de um novo recurso é garantir que ele seja totalmente documentado. No mínimo, isso significa garantir que haja documentação da API, mas também pode ser necessário adicionar um guia de instruções ou de tópicos.

Contribuir com novas funcionalidades

Configurar um ambiente de desenvolvimento

Configurando um ambiente de desenvolvimento

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

Pré-requisitos

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

BeeWare Docs Tools 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 Docs Tools 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 Docs Tools 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 Docs Tools é usar um ambiente virtual e, em seguida, instalar a versão de desenvolvimento de BeeWare Docs Tools e suas dependências.

Clonar o repositório BeeWare Docs Tools

Em seguida, vá para a página BeeWare Docs Tools 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 aplicação 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 Docs Tools e, em seguida:

$ git clone https://github.com/<seu nome de utilizador>/beeware-docs-tools.git

(substituindo seu nome de utilizador do GitHub)

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

$ git clone https://github.com/<seu nome de utilizador>/beeware-docs-tools.git

(substituindo seu nome de utilizador do GitHub)

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

C:\...>git clone https://github.com/<seu nome de utilizador>/beeware-docs-tools.git

(substituindo seu nome de utilizador 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-docs-tools.git
$ git fetch --tags upstream

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

C:\...>git remote add upstream https://github.com/beeware/beeware-docs-tools.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-docs-tools
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

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

C:\...>cd beeware-docs-tools
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 Docs Tools

Agora que você tem o código-fonte, pode fazer uma instalação editável de BeeWare Docs Tools 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 Docs Tools 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 Docs Tools!

Trabalhar a partir de uma filial

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

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 Docs Tools.

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
Evite o aumento do escopo

Evitar o aumento do escopo

O "aumento de escopo" ocorre quando a lista de problemas resolvidos ou de recursos implementados por uma única contribuição cresce significativamente além do que se pretendia quando o trabalho começou. Você começa com um problema simples; descobre um problema intimamente relacionado e decide incluir essa correção também; depois uma terceira… antes que você perceba, você tem uma solicitação pull que fecha 5 problemas e adiciona 3 novos recursos, incluindo dezenas de ficheiros.

O desvio de escopo acontece com todo mundo. É um conceito muito familiar para os desenvolvedores experientes; todos nós já o fizemos várias vezes e experimentamos todos os problemas que o acompanham.

Há motivos muito práticos para evitar o aumento do escopo. Quanto maior for uma contribuição, mais difícil será trabalhar com ela. Torna-se mais difícil identificar casos extremos ou problemas em potencial, o que significa que a qualidade geral da contribuição pode ser reduzida. As revisões também se tornam mais desafiadoras quando o revisor precisa lidar com vários contextos, possivelmente não relacionados. Uma contribuição maior significa mais comentários de revisão e, como colaborador, pode ser difícil acompanhar várias linhas de revisão. Até mesmo sua experiência no GitHub será prejudicada - a interface do utilizador do GitHub ficará mais lenta à medida que o tamanho de um PR aumentar, o que significa que navegar pelos ficheiros por meio da interface do GitHub e tentar deixar comentários de revisão se tornará cada vez mais difícil.

Sempre que encontrar um motivo para adicionar algo à sua contribuição que não faça parte explicitamente da proposta original ou do relatório de bugs, você deve considerar se está entrando em um problema de aumento de escopo. Existem dois recursos distintos que poderiam ser implementados separadamente? Um recurso pode ser implementado com uma limitação ou bug conhecido e esse bug pode ser corrigido em um pull request de acompanhamento? Uma parte de uma correção de bug é independente de outra? Se parte de uma alteração puder ser deixada de fora sem alterar a contribuição original, provavelmente deverá ser.

O desenvolvimento de software é sempre um processo de aprimoramento incremental. Cada contribuição individual deve deixar a base de código em um estado melhor como resultado de ser mesclada, mas é totalmente aceitável deixar bugs ou partes de recursos como trabalho para melhorias futuras. Isso pode significar dividir uma solicitação pull em várias partes que podem ser revisadas independentemente ou registrar um problema para que outra pessoa possa investigar e resolver o problema.

Limitar o escopo de cada contribuição ajuda todos os envolvidos, inclusive você. Seus revisores, e até mesmo você, apreciarão isso.

Implemente o novo recurso

Escrever, executar e testar código

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

Para começar a trabalhar no código, certifique-se de ter um [ambiente de desenvolvimento] configurado e de estar [trabalhando em um branch].

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 Docs Tools 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 Docs Tools. 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 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

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 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

É 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 Docs Tools 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 Docs Tools é 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 ficheiros 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 ficheiros 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.

Depois de ter tudo funcionando, você pode [enviar uma solicitação pull] com suas alterações.

Criar documentação

Documentação da construção

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

Antes de criar a documentação, configure um [ambiente de desenvolvimento].

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 Docs Tools utiliza o tox para criar a documentação. Os comandos tox a seguir devem ser executados no mesmo local que o ficheiro 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 Docs Tools 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 ficheiros 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 Docs Tools 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 Docs Tools 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.

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

Escrever documentação

Redigir documentação

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

Antes de começar a escrever a documentação, certifique-se de que você é capaz de construir a documentação e que está trabalhando em um branch.

Atualização da documentação existente

Se estiver editando os documentos existentes, será necessário localizar o ficheiro no diretório /docs/en. A estrutura do ficheiro segue a estrutura da página, portanto, você pode localizar o ficheiro 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 ficheiro new_doc.md.

Em seguida, você 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 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 ficheiro 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 estiver satisfeito com sua nova documentação, você pode enviar uma solicitação pull com as alterações propostas.

Adicionar uma nota de alteração

Adicionando informações sobre alterações para notas de lançamento

BeeWare Docs Tools utiliza o towncrier para auxiliar na criação das notas de versão de cada versão. Quando você envia uma pull request, ela deve incluir uma change note - essa nota de alteração se tornará a entrada nas notas de versão descrevendo a alteração que foi feita.

Todo pull request deve incluir pelo menos um ficheiro 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 ficheiro 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 Docs Tools 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 utilizador, 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 utilizadores, 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 ficheiros 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 ficheiros 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 Docs Tools. Se essa pasta estiver vazia, provavelmente é porque BeeWare Docs Tools publicou recentemente uma nova versão; os ficheiros 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 ficheiro 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

Enviando 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 ficheiros 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 ficheiros 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 Docs Tools/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare Docs Tools.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 Docs Tools/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare Docs Tools.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 Docs Tools/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare Docs Tools.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 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 da Web na página de criação de PR.

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.

gh pr create

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

Conteúdo da solicitação de 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.

Sua solicitação de pull deve seguir o modelo de solicitação de pull do BeeWare. Se você criou sua solicitação de pull usando a interface web do GitHub, esse modelo será fornecido como ponto de partida para a descrição da sua solicitação. Se, por engano, você criar uma solicitação de pull sem usar esse modelo, poderá editá-la para adicionar o conteúdo do modelo — mas o conteúdo do modelo deve 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 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.

As ferramentas de IA tendem especialmente a gerar mensagens de pull request prolixas e pouco úteis. Se você usar uma ferramenta de IA para gerar seu PR, você é responsável por garantir que a descrição do pull request seja concisa e contenha apenas informações úteis para o processo de revisão. Você não precisa, por exemplo, incluir detalhes sobre um “regime de testes” que descreva como executar o conjunto de testes, nem uma “justificativa” para explicar por que um bug precisa ser corrigido. Corpos de pull requests excessivamente prolixos podem resultar no fechamento do seu pull request sem que ele seja revisado, pois não respeitam os recursos limitados da equipe principal.

O modelo de solicitação de pull do BeeWare

O modelo de pull request do BeeWare pull request template não é opcional. Exigimos que todas as solicitações de pull sigam este modelo. Sua solicitação de pull não será analisada se estiver faltando a seção “Lista de verificação de PR” ou se suas respostas às perguntas com caixas de seleção estiverem incompletas ou inconsistentes. Se você usou uma ferramenta de IA para gerar sua solicitação de pull, você deve 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 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.

Como parte do envio de uma solicitação pull, você precisará incluir uma [nota de alteração] antes que ela possa ser [revisada].