Como fazer seu primeiro PR open source

Good First Issue,
contributorsopen-sourcepull-requests

A parte difícil do seu primeiro pull request open source geralmente não é Git, GitHub ou a mecânica de abrir um PR. A parte difícil é escolher um trabalho pequeno, atual, compreensível e com boa chance de receber review de mantenedor.

Good First Issue foi criado em torno dessa decisão. Ele ajuda você a sair de "quero contribuir" para "esta é uma issue realista, em um repositório ativo, com contexto suficiente para eu abrir um PR útil".

Comece pelo tipo certo de issue

Comece na página de issues. Busque palavras de ferramentas que você já conhece, filtre por label ou linguagem e ordene os resultados para não começar por trabalho parado.

Bons pontos de entrada incluem:

Não trate a label como garantia. Trate como ponto de partida. Uma boa first issue ainda precisa de escopo claro, repositório responsivo e informação suficiente para você verificar sua mudança.

Leia a issue como reviewer

Antes de clonar qualquer coisa, abra a página de detalhes da issue e veja os sinais que dizem se o trabalho vale seu tempo. Confira labels, repositório, linguagem principal, stars, comentários, reações, responsáveis, descrição e link de origem no GitHub.

Depois leia os metadados do Contributor guide como uma segunda passada. Good First Issue resume sinais como tech stack, domínio, tipo da issue, dificuldade, tempo estimado, status de atividade, clareza, pré-requisitos, facilidade para iniciantes e direção de pesquisa.

Você está procurando alinhamento:

  • A descrição da issue mostra como o sucesso se parece.
  • O repositório tem atividade recente suficiente para tornar review plausível.
  • A stack exigida está perto de algo que você consegue rodar localmente.
  • A discussão não mostra outra pessoa já avançada na mesma correção.
  • A direção de pesquisa dá um próximo passo, não só um desejo vago.

GitHub continua sendo a fonte da verdade. Good First Issue indexa e resume dados públicos, e esses dados podem ficar desatualizados. Se a issue estiver fechada, já atribuída ou contrariada por um comentário mais recente de mantenedor no GitHub, confie no GitHub.

Escolha um escopo minúsculo

No seu primeiro PR, otimize para review. Um mantenedor deve conseguir abrir seu diff e entender a mudança em poucos minutos.

Bons primeiros escopos costumam ser:

  • Melhorias de documentação.
  • Testes que reproduzem um comportamento pequeno e conhecido.
  • Pequenas correções de bug com resultado esperado claro.
  • Polimento de UI quando a saída desejada é óbvia.
  • Exemplos, ajustes de README ou instruções de setup que você consegue verificar.

Evite trabalho que mexe em migrations de banco de dados, autenticação, segurança, automação de release, política de dependências, APIs públicas, grandes features ou decisões de produto pouco claras. Isso pode ser valioso depois, mas raramente é o melhor primeiro PR porque a superfície de review é grande.

Avise antes de codar

Quando tiver um escopo pequeno em mente, deixe um comentário curto na issue do GitHub antes de começar. Você não está pedindo permissão para contribuir com open source; está verificando se o escopo proposto ainda bate com o que mantenedores querem.

Hi! I would like to work on this as my first contribution to the project.

My plan is to update <small, specific area> by <brief change>. Does that scope still make sense?

If there is already a preferred approach, I am happy to follow it.

Se um mantenedor responder com orientação, siga. Se ninguém responder, mas a issue estiver claramente aberta e sem responsável, você ainda pode fazer um PR pequeno e bem testado. Mantenha o diff estreito para ser fácil dizer sim, não ou "ajuste esta parte".

Fork, branch, teste e abra o PR

Depois de ter um plano com escopo, use primeiro a documentação de contribuição do próprio repositório. Se ela não especificar um fluxo, esta versão compacta costuma bastar:

gh repo fork OWNER/REPO --clone
cd REPO
git checkout -b fix-small-specific-thing

# Install dependencies with the project's documented package manager.
<install command>

# Make the smallest change that solves the issue.

# Run the relevant checks before opening the PR.
<test command>

git status
git add <changed files>
git commit -m "fix: update small specific thing"
git push -u origin fix-small-specific-thing
gh pr create --fill

Para um playbook mais completo, comando por comando, use o Contributor guide.

O que deixa o PR pronto para mantenedor

Um PR pronto para mantenedor explica a mudança, o caminho de teste e qualquer limite que o reviewer deve saber antes de abrir o diff. Você não precisa escrever um ensaio. Precisa dar contexto suficiente para o reviewer não ter que reconstruir sua intenção só pelo código.

## What changed

- Updated <area> so <behavior/result>.
- Kept the change limited to <scope>.

## How I tested

- Ran <command>.
- Manually checked <page, flow, or example>.

## Notes

- This addresses <issue link>.
- I am new to this repository, so feedback on the preferred style is welcome.

Depois de abrir o PR, acompanhe os comentários dos mantenedores. Responda com pequenos commits, evite force-push a menos que o projeto peça e mantenha a conversa focada em mergear aquela issue específica.

Quando estiver pronto para escolher outra contribuição, volte para issues ou navegue por repositories e repita o processo: escolha trabalho ativo, compreensível e revisável antes de começar a escrever código.