Ir para o conteúdo

Adicionando documentação

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

Formulários de documentação

A documentação da BeeWare Docs Tools é escrita usando MkDocs e Markdown. 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 aprendizado guiada, com um ponto final de projeto específico.
  • Guia de instruções - Instruções que orientam 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 serão 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 aprimoradas.

Como exemplo, considere a tarefa de escrever uma documentação sobre como assar 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. Ele requer instruções muito específicas e explicações detalhadas que contextualizem as etapas do tutorial. Você não deve presumir nada sobre a experiência do leitor com a ferramenta que está sendo explicada, embora seja razoável presumir alguma proficiência básica em 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 você estiver tentando estabelecer uma prática recomendada ou processos comuns. Explicações sobre aspectos internos devem ser evitadas, assim como caminhos alternativos para o mesmo resultado.

Um tutorial sobre como assar biscoitos é mais do que apenas uma receita. As instruções em um tutorial devem ser acessíveis a alguém que nunca cozinhou antes (como 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 esfriando antes de serem consumidos. O objetivo do tutorial não é produzir um cookie - é 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 em um caso de uso específico do mundo real e em resultados práticos, em vez de explicações teóricas. Ao contrário de um tutorial, você 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 etapas lógicas que precisam ser seguidas para atingir o objetivo do guia.

Uma receita em um 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 aprofundará nos méritos relativos de diferentes tipos de açúcar ou farinha, nem fornecerá instruções detalhadas sobre técnicas ou processos básicos; ela incluirá apenas os ingredientes e as instruções para assar uma fornada de biscoitos, pressupondo que o leitor tenha uma familiaridade básica 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. Ele pode incluir opiniões e perspectivas alternativas, mas o foco no tópico específico do guia deve ser mantido.

Um guia de tópicos sobre como assar biscoitos pode se aprofundar na história dos biscoitos como produto assado, 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 em uma dieta equilibrada. Por si só, não seria um documento muito útil para seguir se você quisesse assar 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 especificidades 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 ela possa incluir exemplos de uso, 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. Ele 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 da BeeWare Docs Tools 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. Ele 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.

Contribuição com documentação

Propondo nova documentação

Propondo um novo recurso

Então, você tem uma ideia sobre um aprimoramento para BeeWare Docs Tools - como você envia essa ideia para consideração?

Faça sua pesquisa

A primeira etapa é pesquisar no rastreador de problemas BeeWare Docs Tools os problemas existentes problemas de recursos (problemas com a tag "aprimoramento"), problemas de documentação (problemas marcados como "documentação"), ou Discussion threads para ver se a ideia já foi sugerida antes. Se tiver sido, e você 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 você não conheça ou conectar sua ideia a outra ideia que talvez não pareça imediatamente relacionada.

Discutir a ideia

Se você não encontrar nenhuma referência existente à sua ideia, inicie um [Discussion thread] (https://github.com/beeware/beeware-docs-tools/discussions). Forneça uma descrição de alto nível da finalidade e do caso de uso de sua ideia. Inclua todas as ideias que você tem sobre como o recurso seria, se implementado, como a forma geral de uma API, a aparência visual de um recurso 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 equipe do BeeWare e o restante da comunidade responderão. A equipe 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 se envolver na discussão, fornecendo outras perspectivas, sugestões ou contrapropostas. O resultado dessa discussão determinará as próximas etapas.

É 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 sua alteração não será aceita.

Isso 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
  • Ele atende a um público de nicho, mas impõe uma sobrecarga significativa a outros utilizadores.

Se determinarmos que sua ideia não é adequada, isso não significa necessariamente que você deva desistir dela. Embora possamos rejeitar uma ideia específica, talvez sejamos muito mais receptivos 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, você poderá ter o recurso, mas sem que as preocupações específicas de manutenção ou as limitações do recurso se tornem uma restrição ao próprio projeto.

Converter em uma solicitação formal de recurso

Depois que a discussão chegar a um consenso sobre a forma de um recurso, você poderá criar um novo [problema de solicitação de recurso] (https://github.com/beeware/beeware-docs-tools/issues/new/choose), no rastreador de problemas {{ nome_formal }}, que resuma a discussão, com links para a discussão para fins de contexto.

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

Se estiver interessado, você pode começar a implementar seu novo recurso.

Configurar um ambiente de desenvolvimento

Configurando um ambiente de desenvolvimento

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

Pré-requisitos

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Configure seu ambiente de desenvolvimento

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

Clonar o repositório BeeWare Docs Tools

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

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

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

(substituindo seu nome de utilizador do GitHub)

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

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

(substituindo seu nome de utilizador do GitHub)

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

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

(substituindo seu nome de utilizador do GitHub)

Definir um repositório upstream

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

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

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

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

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

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

$ git push --tags

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

Criar um ambiente virtual

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

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

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

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

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

Instalar BeeWare Docs Tools

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

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

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

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

Ativar o pré-compromisso

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

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

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

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

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

Trabalhar a partir de uma filial

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

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

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

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

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

Para criar uma ramificação de recurso fix-win11-build, execute:

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

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

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

Evitar o aumento do escopo

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

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

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

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

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

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

Documentação da construção

Documentação da construção

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

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

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

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

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

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

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

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

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

Para iniciar o servidor ativo:

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

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

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

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

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

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

O docs-live é uma etapa inicial

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

Construção local

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

Geração de uma compilação local

Para gerar uma compilação local:

(venv) $ tox -e docs

(venv) $ tox -e docs

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

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

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

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

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

(verbo) $ tox -e docs-all

(verbo) $ tox -e docs-all

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

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

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

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

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

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

Linting de documentação

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

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

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

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

  • hiperlinks mortos
  • palavras com erros ortográficos

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

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

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

Redigir documentação

Redigir documentação

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

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

Atualização da documentação existente

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

Adição de nova documentação

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

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

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

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

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

- [Meu novo documento](new_doc.md)

Escrevendo sua documentação

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

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

Quando estiver satisfeito com sua nova documentação, você pode enviar uma solicitação pull com as alterações propostas.

Adicionar uma nota de alteração

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

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

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

Há cinco tipos de fragmentos:

  • feature (recurso): O PR adiciona um novo comportamento ou recurso que não era possível anteriormente (por exemplo, adicionar suporte a um novo formato de empacotamento ou um novo recurso em um formato de empacotamento existente);
  • bugfix: O PR corrige um bug na implementação existente;
  • doc: O PR é uma melhoria significativa na documentação;
  • removal; O PR representa uma alteração incompatível com versões anteriores na API BeeWare Docs Tools API; ou
  • misc; Uma alteração menor ou administrativa (por exemplo, correção de um erro de digitação, um esclarecimento de linguagem menor ou atualização de uma versão de dependência) que não precisa ser anunciada nas notas da versão.

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

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

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

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

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

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

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

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

Envie uma solicitação pull

Enviando uma solicitação pull

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

Trabalhar com pre-commit

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

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

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

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

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

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

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

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

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

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

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

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

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

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

A seguir, um exemplo do que esperar do push, com o URL destacado.

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

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

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

Se você já tiver feito push do branch atual para o GitHub, não receberá o URL novamente. No entanto, há outras maneiras de acessar a URL de criação de PR:

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

A CLI do GitHub: gh

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

gh pr create

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

Conteúdo da solicitação de pull

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

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

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

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

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

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

O modelo de solicitação de pull do BeeWare

O modelo de pull request do BeeWare pull request template não é opcional. Exigimos que todas as solicitações de pull sigam este modelo. Sua solicitação de pull não será analisada se estiver faltando a seção “Lista de verificação de PR” ou se suas respostas às perguntas com caixas de seleção estiverem incompletas ou inconsistentes. Se você usou uma ferramenta de IA para gerar sua solicitação de pull, você deve marcar a caixa relevante e fornecer detalhes na linha “Assistido por:”.

Integração contínua

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

Há um grande número de alterações que podem resultar em falhas de CI. Em termos gerais, não revisaremos um PR que não esteja sendo aprovado na CI. Se você criar uma solicitação pull e a CI falhar, não iniciaremos sua análise até que ela seja aprovada. Se suas alterações resultarem em uma falha, é sua responsabilidade investigar o motivo e resolver o problema.

Quando o CI falhar, os links de falha serão exibidos na parte inferior da página PR, sob o título "Algumas verificações não foram bem-sucedidas". Você verá uma lista de verificações com falha, que aparecerá no topo da lista de todas as verificações se também houver verificações aprovadas. Se você clicar no link de falha, será levado ao registro. O registro geralmente fornece todas as informações necessárias para descobrir o que causou a falha. Leia o registro e tente descobrir por que a falha está ocorrendo e, em seguida, faça o que for necessário para resolvê-la.

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

Para acionar uma nova execução de CI, você precisa enviar novas alterações para sua ramificação.

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

As verificações pre-commit e towncrier

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

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

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

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