Como contribuir com open source pela primeira vez: do good first issue ao pull request

Você abre a aba de issues de um projeto que admira, lê três linhas de uma discussão sobre arquitetura interna, vê dezenas de mantenedores trocando referências que você não reconhece e fecha a aba. "Quando eu souber mais, eu contribuo." Esse "quando eu souber mais" nunca chega — porque a sensação de não estar pronto não some com estudo isolado, ela some com a primeira contribuição aceita. A boa notícia: a barreira de entrada do open source é muito mais baixa do que essa cena sugere. A maior parte das primeiras contribuições não é código complexo. É documentação, um typo, um teste que faltava, uma tradução. Este guia mostra o caminho concreto do zero até o seu primeiro pull request merjado, sem romantismo e sem etapas que ninguém faz na prática.

Antes de qualquer código: escolha o projeto certo

O erro número um de quem começa é mirar alto demais. Você quer contribuir para o React, o Kubernetes ou o Linux porque são os nomes que conhece — e justamente por isso são os piores lugares para começar. Projetos gigantes têm processos pesados, milhares de issues abertas e mantenedores sem tempo de fazer hand-holding.

Critérios práticos para um bom primeiro projeto:

• Você já usa. Contribuir para uma ferramenta que faz parte do seu dia a dia significa que você entende o problema sem precisar estudar o domínio do zero.
• Está ativo, mas não é gigante. Verifique a data do último commit e dos últimos PRs merjados. Um projeto com PRs respondidos nas últimas duas semanas é um sinal verde.
• Tem CONTRIBUTING.md. A presença desse arquivo na raiz indica que o mantenedor pensou no fluxo de quem chega de fora.
• Tem issues marcadas como acessíveis. É aqui que entra o filtro mais útil de todos.

Se a ideia de software de código aberto ainda é nebulosa para você — por que empresas pagam gente para manter código que dão de graça, como a licença muda o que você pode fazer —, vale ler antes o que é software open source, que cobre o lado conceitual. Aqui o foco é puramente a mão na massa.

Onde encontrar a sua primeira issue

A label good first issue é a convenção universal para tarefas que um mantenedor considera resolvíveis por alguém de fora, sem contexto profundo do projeto. A label help wanted é o passo seguinte: tarefas que o time quer ajuda mas não necessariamente triviais.

Você não precisa caçar repo por repo. Existem agregadores que listam essas issues filtradas por linguagem:

• goodfirstissue.dev e goodfirstissues.com — listam issues abertas com a label, filtráveis por stack.
• CodeTriage — você assina projetos e recebe uma issue por dia no e-mail.
• A própria busca do GitHub: label:"good first issue" language:python state:open.

Dica que economiza frustração: antes de pegar uma issue, confira se ela já não tem alguém comentando "I'm working on this" ou um PR vinculado. Pegar uma issue já em andamento é o jeito mais rápido de ter seu trabalho descartado.

O fluxo técnico, passo a passo

O modelo padrão do GitHub é fork → branch → PR. Você não tem permissão de escrever no repositório original, então trabalha numa cópia sua (o fork) e pede que as mudanças sejam puxadas de volta (o pull request).

# 1. Faça o fork pela interface do GitHub (botão "Fork"), depois clone o SEU fork
git clone https://github.com/SEU-USUARIO/projeto.git
cd projeto

# 2. Adicione o repositório original como "upstream" para sincronizar depois
git remote add upstream https://github.com/ORG-ORIGINAL/projeto.git

# 3. Crie uma branch descritiva — nunca trabalhe na main
git checkout -b fix/corrige-link-quebrado-no-readme

# 4. Faça a mudança, depois um commit claro
git add .
git commit -m "docs: corrige link quebrado na seção de instalação"

# 5. Envie a branch para o SEU fork
git push origin fix/corrige-link-quebrado-no-readme

Depois do push, o GitHub mostra um banner "Compare & pull request". Clique nele para abrir o PR contra o repositório original.

Um detalhe que muita gente ignora e gera retrabalho: rode os testes e o linter antes de abrir o PR. Quase todo projeto tem um comando como npm test, pytest ou make lint. Se o CI do projeto reprovar seu PR por um detalhe de formatação que você poderia ter pego localmente, você só adicionou ruído à fila do mantenedor.

Como escrever um pull request que é aceito

O código é metade do trabalho. A outra metade é fazer o mantenedor entender, em trinta segundos, o que você mudou e por quê. Um PR que abre uma discussão de revisão tem três partes:

1. Título no padrão do projeto. Muitos usam Conventional Commits (fix:, docs:, feat:). Olhe os PRs anteriores e imite o estilo.
2. Descrição que liga à issue. Escreva Closes #123 para vincular automaticamente. Explique o que mudou e, se relevante, como você testou.
3. Escopo pequeno. Um PR resolve uma coisa. Não aproveite a viagem para refatorar três arquivos vizinhos — isso transforma uma revisão de cinco minutos numa de uma hora e derruba a chance de merge.

Exemplo de descrição que funciona:

## O que muda
Corrige o link da seção "Instalação" no README, que apontava para
uma página 404 após a migração da documentação.

## Como testei
Cliquei no link renderizado pelo preview do GitHub e confirmei que
agora abre a página correta.

Closes #482

Quando o review vier — e vai vir, com pedidos de mudança —, encare como parte normal do processo, não como rejeição. Revisão existe para manter a qualidade, não para te julgar. Responda aos comentários, aplique os ajustes com novos commits na mesma branch (o PR atualiza sozinho) e seja breve e educado. Mantenedores são, na imensa maioria, voluntários doando o tempo livre deles.

Contribuição não é só código

Se a ideia de mexer no código de outra pessoa ainda intimida, comece por onde a barreira é quase zero e o valor é real:

• Documentação. READMEs com instruções desatualizadas, exemplos que não rodam mais, seções confusas. Você acabou de passar pela dor de não entender — corrija para o próximo.
• Tradução. Muitos projetos querem docs em português e não têm quem faça.
• Reproduzir e detalhar bugs. Pegar uma issue vaga, reproduzir o problema e adicionar passos exatos é uma contribuição que mantenedores adoram.
• Testes. Adicionar um caso de teste que faltava cobre uma lacuna real e ensina você a base de código no processo.

Essas contribuições contam exatamente igual no seu histórico do GitHub e, muitas vezes, são a porta de entrada para issues de código no mesmo projeto.

Perguntas frequentes

Como começar a contribuir com open source sendo iniciante?

Escolha um projeto que você já usa, procure issues com a label good first issue, leia o CONTRIBUTING.md e comece por documentação ou um bug simples. Não tente contribuir para projetos gigantes como React ou Linux logo de cara — eles têm processos pesados e pouco espaço para hand-holding.

Preciso ser bom em programação para contribuir?

Não para a primeira contribuição. Documentação, tradução, reprodução de bugs e correção de typos são contribuições legítimas que não exigem código. Elas constroem familiaridade com o projeto e abrem caminho para tarefas técnicas depois.

O que é um "good first issue"?

É uma label que mantenedores aplicam em tarefas consideradas resolvíveis por alguém de fora, sem conhecimento profundo do projeto. É o ponto de partida desenhado especificamente para quem chega de primeira viagem. A label help wanted é o nível seguinte.

E se meu pull request for rejeitado?

Rejeição direta é rara; o mais comum é o mantenedor pedir mudanças. Trate isso como conversa, não veredito. Aplique os ajustes pedidos, responda aos comentários e atualize a branch. Se o PR for fechado mesmo assim, peça o motivo de forma educada — quase sempre é questão de escopo ou de outra pessoa já estar resolvendo aquilo.

O que levar deste guia

A diferença entre quem fica anos dizendo "um dia eu contribuo" e quem tem dez PRs merjados não é talento — é ter feito o primeiro. Escolha um projeto que você usa, pegue uma good first issue, abra um PR pequeno e bem descrito, e absorva o review sem levar pro pessoal. O primeiro merge muda a sua relação com qualquer software de código aberto: você para de ver esses projetos como caixas-pretas mantidas por gênios inacessíveis e passa a ver código que você também pode tocar.