Ir para o conteúdo

Adicionar documentação

Pode ter o melhor software do mundo, mas se ninguém souber como usa-lo, qual é o objetivo? A documentação sempre pode ser melhorada - e precisamos da sua ajuda!

Formulários de documentação

A documentação de BeeWare é escrita usando MkDocs e Markdown. O nosso objetivo é seguir a estrutura Diataxis para estruturar a documentação.

A estrutura Diataxis descreve quatro "formas" de documentação:

  • Tutorial - Uma experiência de aprendizagem guiada, com um ponto final de projeto específico.
  • Guia de instruções - Instruções que guiam o leitor em direção a um objetivo ou resultado específico.
  • Guia de tópicos - Uma discussão de uma única ideia, explicada de forma que os conceitos subjacentes fiquem claros.
  • Referência - Descrições técnicas de APIs específicas ou outras interfaces.

Antes de iniciar qualquer contribuição de documentação, é importante identificar qual formulário é o mais adequado. Muitas propostas de documentação vão ser descritas inicialmente como uma solicitação de "um tutorial sobre X" - mas, na maioria dos casos, o que é realmente necessário é um guia de instruções, um guia de tópicos ou informações de referência melhoradas.

Como exemplo, considere a tarefa de escrever uma documentação sobre como cozer biscoitos.

Tutorial

Um tutorial é uma introdução, especialmente voltada para iniciantes, cujo objetivo deve ser levar o leitor de um ponto de partida limpo a um produto acabado. Requer instruções muito específicas e explicações detalhadas que deem contexto aos passos do tutorial. Não deve presumir nada sobre a experiência do leitor com a ferramenta que está sendo explicada, embora seja razoável assumir alguma proficiência básica de Python.

O tutorial deve conter pontos de controle regulares em que o leitor possa estabelecer que conseguiu fazer o que foi descrito. Em cada ponto de controle, os critérios de sucesso devem ser claros. Os casos de falha conhecidos devem ser claramente delineados, incluindo explicações de quaisquer erros ou problemas prováveis que o leitor possa enfrentar. As coisas que mudam como resultado das ações tomadas pelo leitor devem ser apontadas, mesmo que pareçam óbvias. A repetição é incentivada, especialmente se estiver tentando estabelecer uma prática recomendada ou processos comuns. Explicações sobre aspetos internos devem ser evitadas, assim como caminhos alternativos para o mesmo resultado.

Um tutorial sobre como cozer biscoitos é mais do que apenas uma receita. As instruções num tutorial devem ser acessíveis a alguém que nunca cozinhou antes (como a uma criança) e precisam levar em conta coisas que um cozinheiro experiente consideraria óbvias, como o creme de açúcar e manteiga, o processo de pré-aquecimento do forno ou o tempo que os biscoitos devem ficar a arrefecer antes de serem consumidos. O objetivo do tutorial não é produzir um biscoito - é transmitir os fundamentos da panificação. O biscoito resultante é a guloseima saborosa que convence alguém a realizar o tutorial em primeiro lugar.

Guia de instruções

Um guia de instruções deve se concentrar num caso de uso específico do mundo real e em resultados práticos, em vez de explicações teóricas. Ao contrário dum tutorial, pode presumir alguma familiaridade com as ferramentas existentes. O leitor deve ser capaz de seguir o guia do início ao fim e atingir a meta, mas talvez precise de algum conhecimento prévio para fazer isso. Ele deve incluir um conjunto de instruções concretas ou passos lógicos que precisam ser seguidos para atingir o objetivo do guia.

Uma receita num livro de receitas é um bom exemplo de um guia de instruções. Há muitas receitas de biscoitos com gotas de chocolate, e todas elas têm características comuns, mas qualquer receita específica deve ser possível de ser seguida do início ao fim e ter um resultado consistente. Uma boa receita de biscoito com gotas de chocolate não se vai aprofundar nos méritos relativos de diferentes tipos de açúcar ou farinha, nem vai fornecer instruções detalhadas sobre técnicas ou processos básicos; ela vai incluir apenas os ingredientes e as instruções para cozer um lote de biscoitos, pressupondo que o leitor esteja basicamente familiarizado com panificação.

Guia de tópicos

Um guia de tópicos descreve um único assunto ou ideia. Ele pode incluir exemplos de código ou instruções, mas seu foco é muito maior em fornecer uma imagem de alto nível de um conceito geral. Pode incluir opiniões e perspetivas alternativas, mas o foco no tópico específico do guia deve ser mantido.

Um guia de tópicos sobre como cozer biscoitos pode aprofundar-se na história dos biscoitos como produto cozido, explorar a maneira como os processos industrializados resultam em diferentes tipos de biscoitos em comparação com os biscoitos caseiros ou sugerir maneiras pelas quais os biscoitos podem ser incorporados numa dieta equilibrada. Por si só, não seria um documento muito útil para seguir se quisesse cozer um biscoito, mas poderia fornecer o histórico que permitiria a alguém familiarizado com panificação personalizar com sucesso uma receita de biscoito existente.

Referência

A documentação de referência é orientada a informações, descrevendo as especificações da operação de uma biblioteca de ferramentas. Muitas vezes, elas podem ser geradas a partir do próprio código, mas uma boa documentação de API pode exigir mais explicações e contexto. Embora às vezes possa incluir exemplos de uso, as explicações detalhadas devem ser evitadas.

Um guia de referência em panificação pode descrever os tipos de açúcar que podem ser usados e detalhar suas propriedades quando usados na panificação. Descreveria fatos literais sobre o açúcar, mas uma discussão mais ampla sobre a escolha entre os tipos de açúcar deveria ser o assunto de um guia de instruções ou tópico. As informações nutricionais encontradas na maioria dos alimentos embalados seriam consideradas documentação de referência.

Estilo de documentação

A documentação de BeeWare segue as diretrizes descritas no guia de estilo da documentação. Esse guia inclui estilo e formatação básicos e o processo de verificação ortográfica. Também aborda vários detalhes da sintaxe do Markdown, como a sintaxe do link de referência, dicas para trabalhar com blocos de código e manipulação de imagens.

Contribuir com documentação

Propor nova documentação

Propor uma nova funcionalidade

Assim se tiver uma ideia sobre uma melhoria para BeeWare - como submete essa ideia para consideração?

Faça a sua pesquisa

A primeira etapa é pesquisar no rastreio de problemas BeeWare os problemas existentes problemas de recursos (problemas com etiqueta "enhancement"), problemas de documentação (problemas marcados como "documentação"), ou Linhas de discussão para ver se a ideia já foi sugerida antes. Se tiver sido, e tiver um novo contexto ou ideias para acrescentar, inclua-os no tópico existente. Se precisar de ajuda com sua pesquisa, pergunte no canal #dev no BeeWare Discord. Talvez possamos indicar os tópicos existentes, fornecer um contexto que talvez não conheça ou ligar a sua ideia a outra ideia que talvez não pareça imediatamente relacionada.

Discutir a ideia

Se não encontrar nenhuma referência existente à sua ideia, inicie uma Linha de discussão. Forneça uma descrição de alto nível da finalidade e do caso de uso de sua ideia. Inclua todas as ideias que tem sobre como o recurso seria, se implementado, como a forma geral de uma API, a aparência visual de uma capacidade ou o documento que seria adicionado. Se for o caso, inclua também qualquer pesquisa que tenha feito sobre como a sua ideia se manifestaria em diferentes plataformas.

Quando o tópico de discussão for aberto, a equipa do BeeWare e o resto da comunidade irão responder. A equipa principal terá como objetivo fornecer pelo menos uma impressão inicial da sua ideia dentro de dois dias úteis. Se uma ideia for especialmente complexa, uma análise mais detalhada poderá levar até uma semana. Eventos como feriados e conferências podem fazer com que esses prazos sejam um pouco mais longos.

Esta é sua oportunidade de participar de uma conversa sobre sua ideia. Podemos solicitar mais detalhes ou contexto. Outros membros da comunidade também poderão envolver-se na discussão, fornecendo outras perspetivas, sugestões ou contrapropostas. O resultado dessa discussão determinará os próximos passos.

É importante entender que nem todas as ideias serão aceitas. O motivo pelo qual esse processo começa com uma proposta é para evitar que você faça todo o trabalho e acabe descobrindo que há um motivo pelo qual a sua alteração não vai ser aceite.

Isto não significa que não seja uma boa ideia! Pode haver motivos técnicos para que ela não possa ser implementada. Por exemplo, podemos rejeitar uma ideia se:

  • Seria difícil ou impossível implementar de forma confiável em todas as plataformas suportadas; ou
  • Seria difícil de manter, ou a manutenção exigiria acesso a tecnologia ou software que não está amplamente disponível; ou
  • Atende a uma ninharia de público, mas impõe uma sobrecarga significativa aos outros utilizadores.

Se determinarmos que a sua ideia não é adequada, isso não significa necessariamente que deva desistir dela. Embora possamos rejeitar uma ideia específica, talvez sejamos muito mais recetivos a adicionar uma interface de plug-in ou outro ponto de extensão que permita manter o mesmo recurso como uma biblioteca externa. Dessa forma, poderá ter o recurso, mas sem que as preocupações específicas de manutenção ou as limitações do recurso se tornem numa restrição ao próprio projeto.

Converter num pedido formal de funcionalidade

Depois que a discussão chegar a um consenso sobre a forma de uma funcionalidade, poderá criar um novo problema de pedido de funcionalidade, no rastreio de problemas BeeWare, que resuma a discussão, com atalhos para a discussão para fins de contexto.

Não precisa implementar a sua proposta de funcionalidade por conta própria; pode abrir um problema com os detalhes do que está a propor. No entanto, o simples facto de publicar a questão não significa que ela será implementada para si. Vai precisar esperar que ela seja potencialmente escolhida por outra pessoa interessada no mesmo recurso, seja outro membro da comunidade ou a equipa principal; no entanto, não há garantia de que isso aconteça. Se quiser a implementação garantida, vai precisar de implementa-la você mesmo ou pagar a alguém para implementa-la por si.

Se estiver interessado, pode começar a implementar a sua nova funcionalidade.

Configurar um ambiente de desenvolvimento

Configurar um ambiente de desenvolvimento

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

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

Trabalhar a partir de um ramo

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

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

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

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

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

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

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

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

(.venv) C:\...>git switch -c fix-win11-build
Evite o aumento do escopo

Evitar o deslizar do escopo

A "expansão 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. Começa com um problema simples; descobre um problema intimamente relacionado e decide incluir essa correção também; depois uma terceira… antes que perceba, tem um pedido de puxar que fecha 5 problemas e adiciona 3 novas funcionalidades, incluindo dezenas de ficheiros.

Expansão de escopo acontece a todos. É 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 a expansão 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 a sua experiência no GitHub vai 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 vai 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 bug, deve considerar se está a entrar num problema de expansão 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 num pedido de puxar 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 melhoria incremental. Cada contribuição individual deve deixar a base de código num estado melhor como resultado de ser fundida, mas é totalmente aceitável deixar bugs ou partes de recursos como trabalho para melhorias futuras. Isso pode significar dividir um pedido de puxar em várias partes que podem ser revistas independentemente ou registar 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ê. Os seus revisores, e até mesmo você, vão apreciar isso.

Compilar documentação

Construir documentação

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

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

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

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

Antevisão da documentação em tempo real

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

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

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

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

Para iniciar o servidor de tempo real:

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

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

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

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

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

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

O docs-live é um passo inicial

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

Compilação local

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

Gerar uma compilação local

Para gerar uma compilação local:

(venv) $ tox -e docs

(venv) $ tox -e docs

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

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

Gerar uma compilação local traduzida

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

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

(venv) $ tox -e docs-all

(venv) $ tox -e docs-all

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

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

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

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

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

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

Análise sintática da documentação

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

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

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

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

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

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

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

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

Escrever documentação

Escrever documentação

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

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

Atualizar a documentação existente

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

Adicionar nova documentação

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

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

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

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

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

- [Meu novo documento](new_doc.md)

Escrever a sua documentação

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

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

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

Adicionar uma nota de alteração

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

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

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

Há cinco tipos de fragmentos:

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

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

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

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

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

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

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

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

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

Submeter um pedido de puxar

Submeter um pedido de puxar

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

Trabalhar com pré-submissão

Quando submete qualquer alteração, a pré-submissão é executada automaticamente. Se houver algum problema encontrado com a submissão, isso fará com que a submissão falhe. Sempre que possível, a pré-submissão fará as alterações necessárias para corrigir os problemas encontrados. No exemplo a seguir, um problema de formatação de código foi encontrado pela verificação ruff:

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Falhad
- hook id: ruff-format
- foram modificados ficheiros por este gancho

1 ficheiro reformatado, 488 ficheiros não alterados

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

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Falhad
- hook id: ruff-format
- foram modificados ficheiros por este gancho

1 ficheiro reformatado, 488 ficheiros não alterados

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

(.venv) C:\...> git add some/interesting_file.py
(.venv) C:\...> git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Falhad
- hook id: ruff-format
- foram modificados ficheiros por este gancho

1 ficheiro reformatado, 488 ficheiros não alterados

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

Nesse caso, o ruff corrigiu automaticamente o problema; portanto, pode adicionar novamente todos os ficheiros que foram modificados como resultado das verificações de pré-submissão e confirmar novamente a alteração. Entretanto, algumas verificações vão exigir que faça modificações manuais. Depois de fazer essas alterações, adicione novamente os ficheiros modificados e faça a submissão novamente.

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 ficheiro alterado, 4 inseridos(+), 2 apagados(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 ficheiro alterado, 4 inseridos(+), 2 apagados(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 ficheiro alterado, 4 inseridos(+), 2 apagados(-)

Quando tudo for aprovado, verá uma mensagem indicando que a submissão foi finalizada, e o registo do git vai mostrar a submissão como a adição mais recente. Agora está pronto para empurrar para o GitHub.

Envie suas alterações para o GitHub e crie o seu pedido de puxar

Na primeira vez que empurrar para o GitHub, vai receber um URL que o vai levar diretamente à página do GitHub para criar um novo pedido de puxar. Siga p URL e crie o seu pedido de puxar.

O seguinte mostra um exemplo do que esperar do push, com o URL destacado.

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

Se já tiver feito push do ramo atual para o GitHub, não vai receber o URL novamente. No entanto, há outras maneiras de aceder ao URL de criação de PR:

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

A CLI do GitHub: gh

O GitHub fornece a CLI GitHub, que lhe dá acesso a muitos dos recursos do GitHub a partir do seu terminal, por meio do comando gh. A Documentação da CLI do GitHub cobre todas as funcionalidades.

gh pr create

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

Conteúdo do pedido de puxar

O título de um pedido de puxar deve ser informativo, claro e conciso. Tente manter-lo curto se possível, mas títulos mais longos são aceitáveis, se tal for necessário. Um bom título de PR deve dar a uma pessoa sem nenhum contexto uma ideia razoavelmente sólida do bug ou funcionalidade implementada pelo seu PR.

O seu pedido de puxar tem de seguir o modelo de pedido de puxar do BeeWare. Se criou o seu pedido de puxar usando a interface web do GitHub, esse modelo será fornecido como ponto de partida para a descrição do seu pedido. Se por engano criar um pedido de puxar sem usar esse modelo, poderá edita-lo para adicionar o conteúdo do modelo — mas o conteúdo do modelo tem de ser fornecido e preenchido corretamente.

A descrição do PR deve refletir claramente as alterações no PR. Uma pessoa sem qualquer contexto deve ser capaz de ler a sua descrição e obter uma compreensão relativamente completa do motivo pelo qual a alteração está a ser feita. Evite piadas, expressões idiomáticas, expressões coloquiais e formatação desnecessária, como o uso de letras maiúsculas ou pontuação excessiva; o objetivo é explicar de forma direta o que está a acontecer no seu PR, e evitar esses elementos torna a descrição mais acessível a outras pessoas.

Se houver algum caso de reprodução ou qualquer regime de teste que tenha usado e que ainda não faça parte das alterações presentes no PR, eles devem ser explicados e incluídos no PR. A explicação deve incluir como executa-los e o que fazer para reproduzir o resultado desejado.

Se o seu pedido de puxar resolver o problema nº 1234, deve incluir o texto Fixes #1234 na descrição do pedido de puxar. Isso vai fazer com que o problema seja fechado automaticamente quando o pedido de puxar for fundido. Pode fazer referência a outras discussões, problemas ou pedidos de puxar usando a mesma sintaxe #1234. Pode referir-se a um problema num repositório diferente prefixando o número com - por exemplo, python/cpython#1234 se estiver a referir ao problema 1234 no repositório CPython.

As ferramentas de IA são muito suscetíveis de escrever mensagens de pedido de puxar muito detalhadas e pouco úteis. Se usar uma ferramenta de IA para gerar seu PR, você é responsável por garantir que a descrição do pedido de puxar seja concisa e contenha apenas informações úteis para o processo de revisão. Não precisa, por exemplo, incluir detalhes sobre um “regime de testes” que descreva como executar o conjunto de testes, nem uma “justificação” para explicar porque um bug precisa ser corrigido. Corpos de pedidos de puxar excessivamente detalhados podem resultar no fechar do seu pedido de puxar sem que ele seja revisto, pois não respeitam os recursos limitados da equipa principal.

O modelo de Pedido de Puxar do BeeWare

O modelo de pedido de puxar do BeeWare não é opcional. Exigimos que todos os pedidos de puxar sigam este modelo. O seu pedido não vai ser analisado se estiver a faltar a secção “Lista de verificação de PR”, ou se suas respostas às perguntas com caixas de seleção estiverem incompletas ou inconsistentes. Se usou uma ferramenta de IA para gerar o seu pedido de puxar, você tem de marcar a caixa relevante e fornecer detalhes na linha “Assistido por:”.

Integração contínua

Integração contínua, ou CI, é o processo de executar verificações automatizadas no seu pedido de puxar. Isso pode incluir verificações simples, como garantir que o código esteja formatado corretamente, mas também inclui a execução do conjunto de testes e a criação de documentação.

Há um grande número de alterações que podem resultar em falhas de CI. Em termos gerais, não revemos um PR que não esteja aprovado na CI. Se criar um pedido de puxar e a CI falhar, não vamos iniciar a sua análise até que seja aprovado. Se as suas alterações resultarem numa falha, é da sua responsabilidade investigar o motivo e resolver o problema.

Quando o CI falhar, os atalhos de falha vão aparecer na parte inferior da página PR, sob o título "Algumas verificações não foram bem-sucedidas". Vai ver uma lista de verificações com falha, que aparecerá no topo da lista de todas as verificações se também houver verificações aprovadas. Se clicar no atalho de falha, será levado ao registo. O registo geralmente fornece todas as informações necessárias para descobrir o que causou a falha. Leia o registo e tente descobrir porque a falha está a ocorrer, e depois faça o que for necessário para resolve-la.

Ocasionalmente, uma verificação de CI vai falhar por motivos que não estão relacionados às suas alterações. Isso pode ocorrer devido a um problema na máquina que executa a verificação de CI ou porque uma verificação de CI é instável. Se observar uma falha e tiver certeza de que ela não está relacionada às suas alterações, adicione um comentário ao seu PR para esse fim e nós analisaremos o caso.

Para acionar uma nova execução de CI, precisa empurrar as novas alterações para o seu ramo.

Se encontrar-se numa situação em que precisa de ajuda para fazer com que o CI seja aprovado, deixe um comentário no PR a informar-nos e faremos o possível para ajudar.

As verificações pre-commit e towncrier

Se as verificações pre-commit ou towncrier falharem, isso vai impedir a execução da maioria das demais verificações de CI. Você vai precisar resolver os problemas aplicáveis antes que o conjunto completo de verificações seja executado.

Temos recursos limitados de CI. É importante entender que toda vez que fizer push para o ramo, a CI será iniciada. Se for fazer várias alterações, é melhor fazer essas alterações localmente e envia-las todas de uma vez. O CI só será executado na submissão mais recente num lote, minimizando a carga no nosso sistema de CI.

O processo de submeter o seu PR não é concluído até que seja aprovado pelo CI ou até que forneça uma explicação do motivo pelo qual não foi aprovado.

O seu pedido de puxar pode exigir conteúdo adicional, como uma nota de alteração, antes de poder ser revisado.