Guia do contribuidor

Como entregar seu primeiro pull request

O caminho mais curto e confiável entre encontrar uma issue boa para iniciantes e ter um pull request pronto para review de mantenedor.

Comece aqui

Escolha o seu nível inicial

Use esses cartões como um seletor estático. Escolha aquele que corresponde ao seu estado atual e siga as mesmas fases abaixo.

Iniciante completo

Comece com as ferramentas, o vocabulário e uma alteração apenas na documentação. Seu objetivo é terminar um loop seguro.

Primeiro PR de todos os tempos

Escolha um issue pequeno e recente e mantenha o diferencial focado. Peça confirmação antes de começar a codificar.

Colaborador recorrente

Use o manual como uma lista de verificação e, em seguida, gaste a maior parte de sua energia reproduzindo e testando a correção.

Fase 0

Instale as ferramentas básicas

Você só precisa de ferramentas locais suficientes para clonar o repositório, criar uma ramificação, executar as verificações do projeto e enviar seu trabalho.

git

O Git rastreia seu trabalho e permite aos mantenedores review exatamente o que mudou.

git --version

gh

GitHub CLI ajuda você fork, clonar, autenticar e abrir pull requests sem sair do terminal.

gh auth login
gh repo fork OWNER/REPO --clone --remote

editor

Use um editor que possa pesquisar todo o repositório, executar formatadores e mostrar claramente os arquivos alterados.

code .

Fase 1

Escolha o issue certo

Um good first issue não é apenas pequeno. É atual, compreensível e passível de revisão por alguém que já mantém o projeto.

Reivindique

Deixe um breve comentário nomeando o issue exato e perguntando se o escopo ainda faz sentido.

Leia as regras

Leia CONTRIBUTING, o README, abra pull requests, teste comandos e notas de estilo de código antes de alterar o código.

Garfo + galho

Crie sua própria cópia e trabalhe em um branch com o nome da tarefa, não no main.

Configurar + reproduzir

Instale dependências, reproduza o problema e anote o comando ou tela onde você o viu.

Envie uma pequena diferença

Altere o mínimo de código necessário. Evite refatorações indiretas, atualizações de dependências e formatação não relacionada.

Abra o PR

Explique o que mudou, como você testou e quaisquer limites. Facilite a primeira passagem do reviewer.

Pontos de pausa

Sinais de alerta antes de investir mais tempo

Parar cedo é melhor do que forçar um pull request que não pode ser revisado.

Você não pode executar o projeto localmente após seguir a configuração documentada.

Você não pode executar o projeto localmente após seguir a configuração documentada.

A correção requer adivinhar o comportamento do produto sem a entrada do mantenedor.

A correção requer adivinhar o comportamento do produto sem a entrada do mantenedor.

O issue exige uma grande decisão de recurso, redesenho, migração ou arquitetura.

O issue exige uma grande decisão de recurso, redesenho, migração ou arquitetura.

Um mantenedor pediu aos contribuidores iniciantes que não trabalhassem na área.

Um mantenedor pediu aos contribuidores iniciantes que não trabalhassem na área.

Reference

Glossary

Fork
Sua cópia pessoal de um repositório. Você envia sua filial para lá antes de abrir um pull request.
Branch
Uma linha móvel de trabalho. Use uma ramificação por issue para que suas alterações possam ser revisadas.
Solicitação pull
Uma solicitação para mantenedores para review e mesclar sua ramificação no repositório do projeto.
Diff
O menor conjunto significativo de alterações que resolve o issue sem limpeza não relacionada.
CONTRIBUTING
Uma lista de verificação específica do projeto para configuração, estilo, testes e expectativas pull request.

FAQ

Primeiras perguntas comuns sobre PR

E se o mantenedor não responder há uma semana?

Publique um acompanhamento conciso com seu status atual e uma pergunta direta. Se ainda não houver resposta, escolha outro issue em vez de esperar indefinidamente.

O que devo fazer quando a configuração falha?

Diga o que você tentou, cole o erro exato, inclua o sistema operacional e as versões da ferramenta e solicite a próxima etapa de depuração.

Meu primeiro PR pode ser apenas documentação?

Sim, se o repositório aceitar alterações na documentação. Documentos claros, exemplos, erros de digitação e links quebrados são contribuições legítimas.