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.

Bons sinais

  • O issue é recente ou tem uma resposta do mantenedor.
  • O repositório possui instruções de configuração que ainda funcionam.
  • A mudança esperada pode caber em um pequeno pull request.
  • Testes ou etapas de verificação manual são descritos.

Bandeiras vermelhas

  • Várias pessoas já estão trabalhando no mesmo issue.
  • O issue é vago, antigo ou bloqueado pela discussão do design.
  • A mudança envolve segurança, faturamento, migrações de banco de dados ou automação de lançamento.
  • O projeto não tem atividade recente de mantenedor.

Árvore de decisão

  1. Você pode explicar o pedido em uma frase?
  2. Você pode reproduzir ou verificar o problema localmente?
  3. A mudança pode permanecer pequena e isolada?
  4. Se todos os três forem sim, peça para levar o issue.

Fase 2

O manual de 6 etapas

Mantenha o ciclo chato e previsível. pull requests pequenos são mais fáceis de review, mais fáceis de corrigir e mais fáceis de mesclar.

1

Reivindique

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

2

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.

3

Garfo + galho

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

4

Configurar + reproduzir

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

5

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.

6

Abra o PR

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

gh repo fork OWNER/REPO --clone --remote
cd REPO
git checkout -b docs/fix-install-note
pnpm install
pnpm test
git status
gh pr create --fill

Templates

Modelos de copiar e colar

Adapte o texto, seja específico e evite prometer mais do que pode cumprir.

Reivindicar comentário

Oi! Eu gostaria de trabalhar neste issue.

Pretendo manter a mudança com escopo para:
- ...

Essa abordagem parece certa antes de eu começar?

PR descrição

## O que mudou
- ...

## Como testei
- ...

## Notas
- Esta é minha primeira contribuição para este repositório, então feedback é bem-vindo.

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.
  • 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.
  • 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.

Após a primeira fusão

Transforme uma contribuição em um hábito repetível

Agradeça ao reviewer, observe os comandos que funcionaram, salve as convenções do projeto e procure o próximo issue que é apenas um pouco mais difícil que o anterior.