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

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

Pré-requisitos¶

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

macOSLinuxWindows

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:

$ python3 --version

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:

$ python3 --version

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:

macOSLinuxWindows

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

$ git clone https://github.com/<your username>/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/<your username>/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/<your username>/beeware.git

(substituindo seu nome de usuário do GitHub)

Criar um ambiente virtual¶

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

macOSLinuxWindows

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

macOSLinuxWindows

(.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:

macOSLinuxWindows

(.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:

macOSLinuxWindows

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

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

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 usuário do GitHub ficará mais lenta à medida que o tamanho de um PR aumentar, o que significa que navegar pelos arquivos 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

Fixing a bug or implementing a feature will require you to write some new code.

We have a code style guide that outlines our guidelines for writing code for BeeWare.

Test-driven development¶

A good way to ensure your code is going to do what you expect it to, is to first write a test case to test for it. This test case should fail initially, as the code it is testing for is not yet present. You can then write the code changes needed to make the test pass, and know that what you've written is solving the problem you are expecting it to.

Run your code¶

Once your code is written, you need to ensure it runs. You'll need to manually run your code to verify it is doing what you expect. If you haven't already, you'll want to write a test case for your changes; as mentioned above, this test should fail if your code is commented out or not present.

You'll add your test case to the test suite, so it can be run alongside the other tests. The next step is to run the test suite.

Running tests and coverage¶

BeeWare uses tox to manage the testing process and pytest for its own test suite.

The default tox command includes running:

pre-commit hooks
towncrier release note check
documentation linting
test suite for available Python versions
code coverage reporting

This is essentially what is run by CI when you submit a pull request.

To run the full test suite, run:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

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

The full test suite can take a while to run. You can speed it up considerably by running tox in parallel, by running tox p (or tox run-parallel). When you run the test suite in parallel, you'll get less feedback on the progress of the test suite as it runs, but you'll still get a summary of any problems found at the end of the test run. You should get some output indicating that tests have been run. You may see SKIPPED tests, but shouldn't ever get any FAIL or ERROR test results. We run our full test suite before merging every patch. If that process discovers any problems, we don't merge the patch. If you do find a test error or failure, either there's something odd in your test environment, or you've found an edge case that we haven't seen before - either way, let us know!

In addition to the tests passing, this should report 100% test coverage.

Running test variations¶

Run tests for multiple versions of Python¶

By default, many of the tox commands will attempt to run the test suite multiple times, once for each Python version supported by BeeWare. To do this, though, each of the Python versions must be installed on your machine and available to tox's Python discovery process. In general, if a version of Python is available via PATH, then tox should be able to find and use it.

Run only the test suite¶

If you're rapidly iterating on a new feature, you don't need to run the full test suite; you can run only the unit tests. To do this, run:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Run a subset of tests¶

By default, tox will run all tests in the unit test suite. When you're developing your new test, it may be helpful to run just that one test. To do this, you can pass in any pytest specifier as an argument to tox. These test paths are relative to the briefcase directory. For example, to run only the tests in a single file, run:

macOSLinuxWindows

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

You'll still get a coverage report when running a part of the test suite - but the coverage results will only report the lines of code that were executed by the specific tests you ran.

Run the test suite for a specific Python version¶

By default tox -e py will run using whatever interpreter resolves as python on your machine. If you have multiple Python versions installed, and want to test a specific Python version from the versions you have installed, you can specify a specific Python version to use. For example, to run the test suite on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

A subset of tests can be run by adding -- and a test specification to the command line.

Run the test suite without coverage (fast)¶

By default, tox will run the pytest suite in single threaded mode. You can speed up the execution of the test suite by running the test suite in parallel. This mode does not produce coverage files due to complexities in capturing coverage within spawned processes. To run a single python version in "fast" mode, run:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

A subset of tests can be run by adding -- and a test specification to the command line; a specific Python version can be used by adding the version to the test target (e.g., py310-fast to run fast on Python 3.10).

Code coverage¶

BeeWare maintains 100% branch coverage in its codebase. When you add or modify code in the project, you must add test code to ensure coverage of any changes you make.

However, BeeWare targets multiple platforms, as well as multiple versions of Python, so full coverage cannot be verified on a single platform and Python version. To accommodate this, several conditional coverage rules are defined in the tool.coverage.coverage_conditional_plugin.rules section of pyproject.toml (e.g., no-cover-if-is-windows can be used to flag a block of code that won't be executed when running the test suite on Windows). These rules are used to identify sections of code that are only covered on particular platforms or Python versions.

Of note, coverage reporting across Python versions can be a bit quirky. For instance, if coverage files are produced using one version of Python but coverage reporting is done on another, the report may include false positives for missed branches. Because of this, coverage reporting should always use the oldest version Python used to produce the coverage files.

Understanding coverage results¶

At the end of the coverage test output there should be a report of the coverage data that was gathered:

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

This tells us that the test suite has executed every possible branching path in the code. This isn't a 100% guarantee that there are no bugs, but it does mean that we're exercising every line of code in the codebase.

If you make changes to the codebase, it's possible you'll introduce a gap in this coverage. When this happens, the coverage report will tell you which lines aren't being executed. For example, lets say we made a change to some/interesting_file.py, adding some new logic. The coverage report might look something like:

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

This tells us that line 170, lines 302-307, and a branch jumping from line 320 to line 335, are not being executed by the test suite. You'll need to add new tests (or modify an existing test) to restore this coverage.

Coverage report for host platform and Python version¶

You can generate a coverage report for your platform and version of Python. For example, to run the test suite and generate a coverage report on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Coverage report for host platform¶

If all supported versions of Python are available to tox, then coverage for the host platform can be reported by running:

macOSLinuxWindows

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

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

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

Coverage reporting in HTML¶

A HTML coverage report can be generated by appending -html to any of the coverage tox environment names, for instance:

macOSLinuxWindows

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

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

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

It's not just about writing tests!¶

Although we ensure that we test all of our code, the task isn't just about maintaining that level of testing. Part of the task is to audit the code as you go. You could write a comprehensive set of tests for a concrete life jacket… but a concrete life jacket would still be useless for the purpose it was intended!

As you develop tests, you should be checking that the core module is internally consistent as well. If you notice any method names that aren't internally consistent (e.g., something called on_select in one module, but called on_selected in another), or where the data isn't being handled consistently, flag it and bring it to our attention by raising a ticket. Or, if you're confident that you know what needs to be done, create a pull request that fixes the problem you've found.

///

/// details-abstract | 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".

/// warning | 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:



/// tab | macOS



```console
(venv) $ tox -e docs-live

LinuxWindows

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

INFO    -  [11:18:51] Serving on 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:

macOSLinuxWindows

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

macOSLinuxWindows

(venv) $ tox -e docs-all

(venv) $ 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:

macOSLinuxWindows

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

macOSLinuxWindows

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

- ./path/to/directory/*

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:

- [My new document](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.

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:

macOSLinuxWindows

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

macOSLinuxWindows

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

macOSLinuxWindows

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