Visão geral

Todas as alterações no código e na documentação devem ser enviadas por meio de uma solicitação pull para o repositório do projeto no GitHub.

A maioria dos projetos tem um guia de contribuição dedicado com detalhes específicos para esse projeto ou tipos específicos de contribuição. Essa documentação pode ser encontrada em Read the Docs. Por exemplo, a [Briefcase's documentation] (https://briefcase.readthedocs.io) contém guias de contribuição para ambos code e documentation.

Todos os envios devem obedecer ao Código de conduta do BeeWare Conduta.

Notas de alteração

Vários projetos do BeeWare, principalmente o Briefcase e o Toga, exigem que cada pull request seja enviado com uma nota de alteração. Essas notas de alteração são compiladas juntas quando uma nova versão é cortada para o projeto, produzindo as notas de versão para a nova versão.

O BeeWare usa o [Towncrier] (https://towncrier.readthedocs.io/en/stable/) para gerenciar notas de alteração.

Um arquivo de nota de alteração deve ser criado no diretório changes e nomeado usando esse formato:

<PR/Issue #>.<Change Type>.rst

Por exemplo, um pull request que corrige o problema #42 do GitHub seria nomeado 42.bugfix.rst. Se uma pull request não estiver associada a um problema específico, o número da pull request poderá ser usado em seu lugar. Talvez você precise criar a pull request sem uma nota de alteração para obter um número de pull request alocado e, em seguida, enviar uma atualização que inclua a nota de alteração com o número da pull request recém-alocado.

Os tipos de modificação para a nota de modificação devem ser um dos seguintes:

  • feature
  • bugfix
  • doc
  • removal
  • misc

O tipo misc é reservado para alterações que não afetam os usuários e não precisam ser registradas nas notas de versão. Pequenas correções tipográficas na documentação, atualizações na configuração de CI e correções de bugs para recursos recursos que ainda não foram formalmente lançados são exemplos de recursos que seriam descritos usando os marcadores misc.

Uma nota de alteração deve ser uma única linha de texto, fornecendo um resumo de alto nível da alteração resumo 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 futuros desenvolvedores possam acompanhar o raciocínio de uma alteração. Uma nota de alteração é uma descrição "voltada para o usuário", descrita em termos do novo recurso que está disponível como resultado da alteração. Pode ser útil pensar na nota de alteração como um comunicado à imprensa anunciando a alteração, em vez de uma descrição do commit.

Por exemplo, se você corrigir um bug causado pelo tratamento de datas, a mensagem do commit ou a descrição do pull request poderá ser a seguinte:

Adição de um validador do formato MM-DD-YYYY à cadeia de validação do DateWidget cadeia.

Isso descreve a alteração que foi feita na implementação - detalhes que será útil para a pessoa que estiver revisando o código. No entanto, a nota de alteração correspondente pode ser algo como:

Os widgets de data agora podem aceitar datas no formato americano.

Isso descreve a mudança funcional como será vivenciada pelos usuários finais. usuários finais. Um usuário pode ler essa descrição sem precisar saber nada sobre a implementação.

Estilo de código

Os projetos do BeeWare usam [Pre-commit] (https://pre-commit.com/) para automatizar a a adesão ao estilo do código. Essas verificações são definidas no arquivo arquivo .pre-commit-config.yaml para cada repositório e são automaticamente executadas no CI quando um Pull Request é aberta.

Para automatizar as verificações do Pre-commit em seu ambiente de desenvolvimento local a cada commit do git, execute pre-commit install.

Incluídas verificações de pré-compromisso:

  • Black garante formatação uniforme do código
  • docformatter garante formatação uniforme para docstrings e comentários
  • pyupgrade garante que o código esteja usando as práticas recomendadas mais recentes para Python
  • isort](https://pycqa.github.io/isort/) garante a uniformidade das declarações import uniformes
  • flake8 verifica se há problemas comuns de codificação e problemas de sintaxe
  • Verificações diversas que validam documentos estruturados, como arquivos TOML, e removem espaços em branco desnecessários

Diretrizes adicionais:

  • Evite o uso de "nós" nos comentários, por exemplo, "Loop over" em vez de "We loop over"

  • Use sublinhados, e não camelCase, para nomes de variáveis, funções e métodos nomes

  • Use InitialCaps para nomes de classes (ou para funções de fábrica que retornam classes)

  • Use docstrings no estilo Sphinx e 257; a anotação de tipo com 484 é opcional, mas recomendada.

    Por exemplo:

    def function_name(param1: int, param2: str) -> bool:
    """Exemplo de função com tipos e uma docstring.

    :param param1: O primeiro parâmetro.
    :param param2: O segundo parâmetro.

    Retorna: O valor de retorno. Verdadeiro para sucesso, Falso caso contrário.
    """

  • Nas documentações dos testes, indique o comportamento esperado que cada teste demonstra. Não inclua preâmbulos como "Testa que" ou "Garante que".

  • Reserve referências de tíquetes para problemas obscuros em que o tíquete tenha detalhes adicionais que não podem ser facilmente descritos em documentos ou comentários. Inclua o número do tíquete no final de uma frase como assim:

    def test_foo():
    """Uma docstring de teste tem a seguinte aparência (#123456)."""

  • A menos que especificado de outra forma, siga 8 (com atenção especial para Seção 2).