Contribuindo para o Guia de Empacotamento Python#

O guia é um recurso da comunidade.

TL;DR#

Recebemos contribuições na forma de issues e pull requests:

Se você tem uma ideia de algo que deveria ser incluído no guia, por favor abra uma issue aqui.
Se você encontrar um erro de digitação, sinta-se à vontade para enviar um pull request para modificar o texto diretamente. Ou, se você não se sentir tão confortável com pull requests, sinta-se à vontade para abrir uma issue.
Se você tem interesse em ajudar a traduzir o guia para outros idiomas, dê uma olhada no guia de tradução.
Se você quiser propor uma mudança maior no conteúdo do guia, por favor abra uma issue primeiro!

Se você não tem certeza de como contribuir ou não está familiarizado com git e github, este guia vai te ajudar durante todo o processo.

Como o Guia de Empacotamento Python é estruturado#

O Guia de Empacotamento Python é escrito em myST (uma variante de MarkDown e rST) e usamos o Sphinx, um mecanismo de documentação construído em Python para gerar a versão em HTML que você vê online.

Usamos uma ferramenta chamada Nox para gerenciar o processo de construção do guia.

Duas formas de contribuir#

Você pode contribuir com o guia usando duas abordagens.

A primeira abordagem é usar uma cópia local do guia no seu computador. Essa opção exige uma configuração mais elaborada, mas permite que você construa o guia localmente para verificar se sua contribuição não introduziu nenhum bug antes de enviar um pull request. É a abordagem recomendada para contribuições maiores, como escrever uma seção inteiramente nova.

A segunda abordagem é fazer sua contribuição diretamente no site do GitHub. Essa opção não exige nenhuma configuração no seu computador e, embora sua contribuição ainda seja testada quando você enviar um PR (integração contínua), vai demorar mais para você receber algum feedback caso haja algum problema. É a melhor forma de fazer pequenas contribuições, como corrigir erros de digitação, ou se essa for sua primeira contribuição para open source e a primeira abordagem parecer intimidadora demais.

Fazendo um fork do repositório#

Independentemente da abordagem que você escolher, o primeiro passo é fazer um fork do repositório do Guia de Empacotamento Python para o seu espaço pessoal no GitHub. Você pode fazer isso clicando no botão «Fork» no canto superior direito da página do repositório.

Saiba mais: Fork and Clone GitHub Repos é um bom recurso para aprender mais sobre fork.

Para fazer um fork de um repositório,

Certifique-se de que você está logado no GitHub.
Vá até o repositório do qual você gostaria de fazer um fork, nesse caso o Python Packaging Guide.
No canto superior direito da página há um botão “Fork”. Clique nesse botão. Você será levado a uma nova página onde vai “Create a new fork”. Sinta-se à vontade para manter todas as opções padrão e clicar em “Create fork”. Isso vai criar uma cópia do repositório em https://github.com/<username>/python-package-guide, onde <username> é o seu nome de usuário do GitHub.

Contribuindo pelo site do GitHub#

Como editar um arquivo MarkDown#

O Guia de Empacotamento Python é escrito em myST, uma variante de MarkDown. Você pode editar os arquivos diretamente no site do GitHub. Para fazer isso, navegue até o arquivo que deseja editar e clique no ícone de lápis no canto superior direito do arquivo.

Editar arquivo no GitHub — Uma imagem mostrando como editar um arquivo no GitHub. O ícone de lápis está destacado com um retângulo vermelho.#

Uma imagem mostrando um arquivo sendo editado no GitHub. O conteúdo do arquivo é exibido em um editor de texto.#

Para pré-visualizar suas alterações, clique na aba «Preview changes».

Pré-visualizar alterações no GitHub — Uma imagem mostrando como pré-visualizar alterações no GitHub. O conteúdo do arquivo é exibido em um editor de texto. A aba de preview changes está destacada com um retângulo vermelho.#

Como fazer commit das suas alterações#

When you are done editing the file, click the green «Commit changes…» button in the top-right corner of the editor. GitHub will open a «Propose changes» dialog where you can write a commit message and an optional extended description. Make sure the commit message clearly and concisely describes the changes you made.

Propose changes dialog in GitHub — The GitHub «Propose changes» dialog with the commit message field highlighted.#

After writing your commit message, click the «Propose changes» button to save the commit to your fork.

Contribuindo localmente no seu computador#

Clone o seu repositório com fork#

Para clonar o seu repositório com fork no seu computador, você precisa copiar a URL do seu repositório com fork e executar o seguinte comando no seu terminal:

git clone <URL>

Substitua <URL> pela URL do seu repositório com fork. Você pode encontrar a URL clicando no botão verde «Code» na página do seu repositório com fork.

Clonar repositório no GitHub — Uma imagem mostrando como clonar um repositório no GitHub. A URL do repositório é exibida em um editor de texto. O botão code está destacado com um retângulo vermelho.#

Crie uma nova branch#

Antes de fazer qualquer alteração, você deve criar uma nova branch para trabalhar. Isso vai ajudar a manter suas alterações separadas da branch principal e vai facilitar o envio de um pull request.

Para criar uma nova branch, execute o seguinte comando no seu terminal:

git checkout -b <branch-name>

Crie um ambiente virtual#

Para construir o guia localmente, você precisa criar um ambiente virtual e instalar as dependências. Você pode fazer isso executando os seguintes comandos no seu terminal:

No Windows:

python -m venv .venv
.venv\Scripts\activate

No MacOS e Linux:

python -m venv .venv
source .venv/bin/activate

Instale as dependências de desenvolvimento#

Para instalar as dependências de desenvolvimento, execute o seguinte comando no seu terminal:

python -m pip install -e '.[dev]'

The quotes around '.[dev]' matter if you use zsh, the default shell on macOS. Without them, zsh treats the square brackets as a filename pattern and fails with no matches found.

On Windows they are harmless in PowerShell, but if you use the older cmd.exe prompt you need to remove them and run python -m pip install -e .[dev] instead, because cmd.exe does not strip single quotes.

Faça commit das suas alterações#

Depois de fazer suas alterações, você precisa fazer commit delas no seu repositório local. Para fazer isso, execute os seguintes comandos no seu terminal:

Para ver as alterações que você fez:
```
git status
```
Para adicionar as alterações à staging area:
```
git add .
```

Para fazer commit das alterações:

git commit -m "Your commit message here"

Substitua "Your commit message here" por uma mensagem clara e concisa que descreva as alterações que você fez.

Como construir o guia localmente#

Para construir o guia localmente, você pode usar o comando nox. Isso vai executar a sessão padrão do nox, que constrói o guia e abre ele no seu navegador.

Para ver as diferentes sessões disponíveis, você pode executar o seguinte comando no seu terminal:

nox --list-sessions

Existem diferentes sessões no nox relacionadas à construção dos docs: docs, docs-test, docs-live. Você pode executá-las especificando o nome da sessão depois do comando nox.

docs: essa sessão constrói o guia e abre ele no seu navegador.
```
nox -e docs
```
Para ver o guia construído localmente, abra o arquivo _build/html/index.html no seu navegador.
docs-linkcheck: essa sessão verifica se os links na documentação funcionam
```
nox -e docs-linkcheck
```
Se os testes falharem, você vai ver logs no terminal e em _build/linkcheck_output/output.txt.
docs-test: essa sessão executa os testes do guia.
```
nox -e docs-test
```
Se os testes falharem, você vai ver uma mensagem de erro no seu terminal. Você precisa corrigir os erros antes de enviar o seu pull request.
docs-live: essa sessão constrói o guia e abre ele no seu navegador com live reloading.
```
nox -e docs-live
```
abra a versão local do guia no seu navegador em localhost mostrado no terminal.

Antes de enviar o seu pull request#

Antes de enviar o seu pull request, certifique-se de executar os testes e verificar a formatação do seu código.

nox -e docs-test

Se os testes falharem, você vai ver uma mensagem de erro no seu terminal. Você precisa corrigir os erros antes de enviar o seu pull request. Certifique-se também de verificar a formatação da sua documentação construindo os docs localmente e conferindo se as suas alterações estão corretas.

Enviando um pull request com a sua contribuição#

Como fazer um pull request#

Para abrir um pull request no GitHub, navegue até a página principal do seu repositório com fork e clique na aba «Pull requests».

Aba de pull requests no GitHub — Uma imagem mostrando como navegar até a aba de pull requests no GitHub. A aba de pull requests está destacada com um retângulo vermelho.#

Clique no botão «New pull request».

Botão de novo pull request no GitHub — Uma imagem mostrando como criar um novo pull request no GitHub. O botão de novo pull request está destacado com um retângulo vermelho.#

Escreva um título e uma descrição claros e concisos para o seu pull request. Certifique-se de descrever as alterações que você fez e por que elas são necessárias.

O que acontece quando você envia um pull request (CI/CD)#

Assim que você envia um pull request, uma série de verificações vai ser executada para garantir que as suas alterações não introduzam nenhum bug ou erro. Essas verificações incluem:

Formatação e estilo do código: verifica se o seu código está formatado corretamente, por meio do pre-commit.ci - pr check.
docs build: verifica se a documentação é construída corretamente, usando circleci.
docs build / preview: builds the guide and publishes a Netlify deploy preview (see Pull request previews below). You will see the status of these checks in your pull request.

Pull request checks in GitHub — Uma imagem mostrando o status das verificações em um pull request no GitHub. As verificações são exibidas em uma tabela com um ícone de status ao lado de cada verificação. As verificações estão destacadas com um retângulo vermelho.#

Se alguma dessas verificações falhar, você vai ver uma mensagem de erro no seu pull request. Você precisa corrigir os erros antes que as suas alterações possam ser mescladas.

Verificações de pull request com falha no GitHub — Uma imagem mostrando o status das verificações em um pull request no GitHub. As verificações são exibidas em uma tabela com um ícone de status ao lado de cada verificação. As verificações que falharam e o link de detalhes estão destacados com um retângulo vermelho.#

Para obter mais informações sobre os erros, você pode clicar no link «Details» ao lado da verificação que falhou.

Pull request previews#

This guide uses Netlify deploy previews. After the Netlify check finishes on a pull request, click Details next to the deploy-preview status to open a live build with your changes.

The guide is still deployed live using GitHub Pages: https://www.pyopensci.org/python-package-guide/.

O que esperar do processo de revisão#

Assim que você envia um pull request, um mantenedor do repositório vai revisar as suas alterações e dar um feedback. O processo de revisão pode envolver:

Comentários: quem está revisando pode deixar comentários no seu pull request para fazer perguntas ou dar feedback.
Sugestões: quem está revisando pode sugerir alterações no seu código ou na sua documentação.
Aprovações: assim que quem está revisando estiver satisfeito com as suas alterações, ele vai aprovar o pull request.

Você pode fazer alterações no seu pull request enviando novos commits para a branch. O pull request vai ser atualizado automaticamente com as suas novas alterações.

Assim que o seu pull request for aprovado, ele vai ser mesclado na branch principal e as suas alterações vão ser incluídas no guia.

Ajuda adicional#

Como conseguir ajuda#

TODO: Essa seção deve descrever as opções para encontrar mais ajuda caso contribuidores iniciantes precisem de mais suporte (por exemplo, criar uma issue, postar em um fórum, etc).

Recursos adicionais#

TODO: Também deve incluir links para documentação para iniciantes, como os docs do GitHub.

Anexo#

Exemplos de código#

Este guia usa a diretiva literalinclude do Sphinx sempre que possível para manter o código e o texto separados. O código usado na documentação fica na pasta examples/.

Referenciando código na documentação#

Se já existe um exemplo em outro lugar da documentação que você queira usar, você pode copiar a diretiva literalinclude exatamente como está e os exemplos vão se manter sincronizados.

Se você já vê código na pasta examples que pode usar para uma nova documentação, um novo literalinclude pode ser criado para extraí-lo para o site. Basta um caminho relativo para o código para um literalinclude funcionar, mas você deveria, em quase todos os casos, também fornecer um :language: e :lines:. O primeiro deixa os exemplos de código mais bonitos, e o segundo pode proteger o seu exemplo de futuras modificações no código.

Dica: como alternativa a :lines:, existem também as opções :start-after:, :start-at:, :end-before: e :end-at:. E se o código de exemplo for Python, :pyobject: pode ser uma forma ainda mais durável de manter o mesmo conteúdo de documentação mesmo depois de refatorações no código.

Se você precisar de um código de exemplo que ainda não existe em examples/, veja criando código para documentação.

Criando código para documentação#

Sempre que você encontrar um lugar que poderia se beneficiar de um bloco de código, em vez de escrevê-lo em linha com um code fence (bloco de texto ```) você pode escrevê-lo como um arquivo no seu próprio formato. Seu exemplo pode até já existir; veja referenciando código na documentação.

Se você quiser adicionar um novo exemplo que não se encaixa em nenhum dos arquivos de exemplo existentes, você pode criar um novo arquivo e referenciá-lo em um bloco literalinclude. Se fizer sentido esse arquivo ficar dentro de um dos projetos de exemplo existentes, por favor adicione ele lá; caso contrário, crie uma nova pasta no diretório examples.

Se um exemplo existente estiver incompleto ou fizer sentido adicionar um novo exemplo a um arquivo já existente, vá em frente e adicione, mas tome cuidado para não quebrar o resto do guia. Sempre que possível, estenda o exemplo em vez de reescrevê-lo. Por exemplo, adicione novas funções no final do arquivo, novos métodos depois de todos os já existentes em uma classe.

O código de exemplo é verificado quanto à correção, então adicionar um novo exemplo pode exigir a adição de testes extras para cobertura, e vai exigir a correção de qualquer teste que falhar.

⚠️ AVISO: um cuidado especial deve ser tomado ao modificar código de exemplo já existente, principalmente qualquer modificação além de adicionar ao final do arquivo. Todos os exemplos de código são (potencialmente) exemplos compartilhados. Isso torna os exemplos no guia mais consistentes, mas pode gerar efeitos à distância ao modificar os exemplos para um caso de uso específico. Se você se pegar modificando exemplos existentes, tente executar este comando e depois conferir essas páginas em um novo build.

grep -lr '\.\./examples/path/to/modified\.py' documentation/

Exemplo

Em vez de escrever o código de exemplo em markdown assim

Here is an example Python function:

```python
def is_empty(x):
    return not bool(len(x))
```

O python pode ser extraído para um arquivo .py

def is_empty(x):
    return not bool(len(x))

Here is an example Python function:

:::{literalinclude} ../examples/contributing_example.py
:language: python
:lines: 1-2

Como outro exemplo, se você só precisa mostrar parte de um pyproject.toml, já temos definições completas de projeto, você só precisa encontrar a parte relevante.

Em vez de escrever isso

Classifiers are just a list of plain strings
```toml
classifiers = [
    "Programming Language :: Python :: 3",
    "Operating System :: OS Independent",
]
```

um exemplo poderia ser extraído de um arquivo toml já existente

:::{literalinclude} ../examples/pure-hatch/pyproject.toml
:language: toml
:start-at: classifiers = [
:end-at: ]