Como Contribuir com o Bitcoin Core: Pull Requests e Code Review

Contribuir com o Bitcoin Core significa enviar melhorias para o software que roda a maior parte dos nós da rede Bitcoin, e o processo acontece inteiramente no repositório oficial no GitHub através de pull requests revisados pela comunidade. O caminho mais comum começa com você fazendo um fork do repositório, compilando o Bitcoin Core localmente, encontrando uma good first issue marcada para iniciantes, criando uma branch com a sua alteração, abrindo um pull request bem descrito e então participando das rodadas de code review, em que outros desenvolvedores deixam comentários, sugerem ajustes e registram seus ACKs ou NACKs até que a mudança esteja madura o suficiente para ser mesclada por um mantenedor.

Este guia foi escrito para programadores e desenvolvedores que querem dar o primeiro passo de verdade dentro do Bitcoin Core. Aqui você vai entender o que conta como contribuição, quais são os pré-requisitos, como preparar o ambiente, onde achar as good first issues, como funciona o workflow completo no GitHub, como abrir um pull request que não é ignorado e, principalmente, como funciona o processo de review que é o verdadeiro coração desse projeto.

Se você quer parar de só usar o Bitcoin e começar a construir o Bitcoin, é por aqui que a jornada começa.

Resumo rápido de como contribuir com o Bitcoin Core

• Toda contribuição passa pelo repositório bitcoin/bitcoin no GitHub, no formato de pull requests revisados pela comunidade.
• Você não precisa escrever código para contribuir, já que revisar PRs, testar mudanças, melhorar documentação e traduções também conta muito.
• O fluxo padrão é fork, clone, compilar o node, criar uma branch, commitar com mensagem clara, abrir o PR e iterar com base no review.
• As good first issues são o ponto de partida ideal para quem está começando, porque já vêm filtradas para iniciantes.
• O review usa uma linguagem própria com Concept ACK, Approach ACK, tested ACK, NACK e nits, e entender isso é essencial.
• A forma mais valiosa e mais escassa de contribuir é revisar o trabalho dos outros, não apenas abrir os seus próprios PRs.
• Bitcoin Core é C++ moderno, então saber a linguagem, Git e como compilar o projeto são os pré-requisitos práticos.

O que significa contribuir com o Bitcoin Core?

Antes de qualquer coisa vale alinhar a expectativa, porque contribuir com o Bitcoin Core é bem diferente de contribuir com a maioria dos projetos open source.

O Bitcoin Core é o software de referência da rede e qualquer linha de código que entra ali pode afetar bilhões de dólares em valor e a segurança de milhões de pessoas, então o projeto é deliberadamente conservador, lento e exigente. Isso não é burocracia, é a engenharia de segurança que mantém o Bitcoin funcionando sem falhas há mais de uma década.

Por causa disso, a cultura do projeto valoriza muito mais a revisão cuidadosa do que a velocidade de envio. Um pull request pode ficar aberto por meses, recebendo dezenas de comentários, antes de ser mesclado, e isso é considerado normal e saudável. Quem chega achando que vai abrir uma mudança grande e ver ela aprovada na mesma semana costuma se frustrar, enquanto quem entende a cultura e começa pequeno tende a evoluir rápido dentro da comunidade.

Outro ponto importante é que contribuição não é só código. O projeto depende fortemente de pessoas que revisam pull requests, escrevem e melhoram testes, atualizam documentação, reportam bugs com boa reprodução, ajudam na tradução e respondem dúvidas. Muita gente entra pelo código, mas é justamente a revisão e os testes que estão sempre em falta, então existe espaço enorme para quem quer ser útil mesmo sem mandar uma única linha nova de C++ no começo.

Pré-requisitos antes de contribuir

Não existe um diploma necessário para contribuir, mas existem alguns conhecimentos práticos que vão fazer toda a diferença na sua experiência. O Bitcoin Core é escrito principalmente em C++, então estar confortável com a linguagem, com ponteiros, com a STL e com o modelo de memória ajuda demais. Além disso, é fundamental dominar o Git e o fluxo de trabalho do GitHub, entender como o Bitcoin funciona por dentro e já ter rodado o seu próprio nó pelo menos uma vez para saber o que você está modificando.

Aqui está uma lista dos conhecimentos necessários para contribuir com o Bitcoin Core:

• Conhecimento sólido de C++ moderno, já que é a linguagem principal do projeto.
• Domínio de Git e do fluxo de fork, branch, commit, rebase e pull request no GitHub.
• Entender a fundo o que é o Bitcoin Core e como ele funciona e a arquitetura de um nó completo.
• Saber compilar e rodar o Bitcoin Core do zero com bitcoind e bitcoin-cli.
• Conhecer as redes de teste como regtest e signet, que são onde você valida mudanças sem usar dinheiro real.
• Inglês para ler e escrever, porque toda a comunicação do projeto acontece em inglês.

Se você ainda não tem essa base, o caminho mais inteligente é construir o repertório primeiro. Vale começar pelo nosso guia de como se tornar um desenvolvedor Bitcoin e pela trilha gratuita do Bitcoin Coders, que é a escola técnica da Area Bitcoin pensada justamente para levar você do zero até a linha de frente do desenvolvimento.

Preparando o ambiente, fork, clone e build

O primeiro passo prático é fazer um fork do repositório bitcoin/bitcoin para a sua própria conta no GitHub, clonar esse fork na sua máquina e configurar o repositório original como remote upstream, para que você consiga manter a sua cópia sempre atualizada com o que acontece no projeto.

Antes de rodar qualquer comando, abra o repositório oficial no GitHub e clique no botão Fork, que cria uma cópia do projeto dentro da sua própria conta. Esse fork é o seu espaço de trabalho, onde você pode mexer à vontade sem afetar o projeto original. Feito isso, os comandos abaixo são digitados um a um no terminal do seu computador, e cada linha cumpre uma função específica nessa preparação.

git clone https://github.com/SEU_USUARIO/bitcoin.git
cd bitcoin
git remote add upstream https://github.com/bitcoin/bitcoin.git
git fetch upstream

• git clone https://github.com/SEU_USUARIO/bitcoin.git baixa para o seu computador a cópia do projeto que está no seu fork, e você deve trocar SEU_USUARIO pelo seu nome de usuário do GitHub.
• cd bitcoin entra na pasta do projeto que acabou de ser baixada, que é de onde você vai rodar todos os próximos comandos.
• git remote add upstream ... cadastra o repositório oficial do Bitcoin Core com o apelido upstream, para você conseguir puxar as novidades dele mais tarde.
• git fetch upstream baixa as últimas atualizações desse repositório oficial sem mexer no seu trabalho local.

Em seguida você precisa compilar o projeto para garantir que tudo funciona antes de mexer em qualquer coisa. As versões modernas do Bitcoin Core usam CMake no lugar do antigo autotools, e o build segue o padrão abaixo. Os detalhes completos e as dependências de cada sistema estão na documentação oficial de build.

cmake -B build
cmake --build build -j"$(nproc)"
ctest --test-dir build

• cmake -B build prepara a compilação e cria uma pasta chamada build com tudo o que o computador precisa para montar o programa.
• cmake --build build -j"$(nproc)" compila o Bitcoin Core de fato, e o trecho com nproc manda usar todos os núcleos do seu processador para terminar mais rápido.
• ctest --test-dir build roda a bateria de testes automatizados para confirmar que o programa foi compilado corretamente e está funcionando.

Vale avisar que a primeira compilação costuma demorar bastante e depende de algumas bibliotecas instaladas no seu sistema, então não se assuste com o tempo nem com eventuais erros de dependência, que são justamente o que a documentação oficial de build ajuda a resolver passo a passo.

Compilar e rodar a suíte de testes desde o começo é mais importante do que parece. Isso confirma que o seu ambiente está saudável, te dá uma base limpa para comparar antes e depois da sua mudança e evita que você perca horas debugando um problema que na verdade era do seu setup e não do seu código.

Onde encontrar good first issues

A pior forma de começar no Bitcoin Core é tentar resolver um problema gigante e polêmico logo de cara. Dito isso, a melhor forma é encontrar uma good first issue, que são tarefas marcadas pelos mantenedores como adequadas para quem está chegando agora. O próprio GitHub mantém uma página de contribuição com as issues abertas para iniciantes, e ela é o melhor lugar para achar a sua primeira tarefa.

Vale também passar um tempo apenas observando antes de pegar qualquer coisa. Leia pull requests recentes que foram mesclados, veja como as pessoas descrevem suas mudanças, repare no tom dos comentários de review e entenda quais áreas do código estão mais ativas. Esse período de observação parece improdutivo, mas ele te ensina a cultura do projeto e evita que o seu primeiro PR cometa erros que já foram discutidos cem vezes.

• Comece por issues pequenas e bem definidas, de preferência em áreas que você já entende.
• Comente na issue avisando que você vai trabalhar nela, para não duplicar esforço com outra pessoa.
• Leia o histórico da issue inteira, porque muitas vezes já existe contexto e decisões importantes ali.
• Prefira melhorar testes e documentação no início, já que são contribuições valiosas e de menor risco.

O fluxo de trabalho no GitHub passo a passo

Com o ambiente pronto e uma issue escolhida, o workflow no GitHub segue sempre o mesmo ritmo. Você cria uma branch dedicada para a sua mudança, faz commits pequenos e bem descritos, mantém a sua branch atualizada com o upstream através de rebase e por fim empurra para o seu fork e abre o pull request. Manter cada PR focado em uma única coisa é uma das regras de ouro do projeto.

1. Atualize o seu repositório local com o upstream antes de começar, para partir de uma base recente.
2. Crie uma branch nova e descritiva para a sua alteração, nunca trabalhe direto na master.
3. Faça a mudança e adicione ou ajuste os testes que cobrem o seu código.
4. Commite com mensagens claras no padrão do projeto, usando um prefixo de área e uma descrição objetiva.
5. Rode os testes localmente de novo para garantir que nada quebrou.
6. Empurre a branch para o seu fork e abra o pull request contra a master do bitcoin/bitcoin.

Esse é o ciclo que você vai repetir a cada nova contribuição, e entender o papel de cada linha deixa o processo natural depois das primeiras vezes.

git checkout master
git pull upstream master
git checkout -b corrige-mensagem-de-log
# faça suas alterações e edite os testes
git add .
git commit -s -m "log: corrige mensagem de erro ao carregar bloco"
git push origin corrige-mensagem-de-log

• git checkout master volta para o branch principal do projeto, que é a base limpa de onde tudo parte.
• git pull upstream master atualiza essa base com as últimas mudanças do repositório oficial, para você não trabalhar em cima de código velho.
• git checkout -b corrige-mensagem-de-log cria um branch novo e separado só para a sua alteração, com um nome que descreve o que você vai fazer.
• A linha que começa com # é apenas um comentário e não um comando, ela marca o momento em que você abre o seu editor e de fato altera o código e os testes.
• git add . seleciona todos os arquivos que você modificou para entrarem no próximo registro de mudança.
• git commit -s -m "..." salva essa alteração com uma mensagem curta que explica o que mudou, e a opção -s assina o commit com a sua identidade.
• git push origin corrige-mensagem-de-log envia o seu branch para o seu fork no GitHub, que é o passo final antes de abrir o pull request pela própria interface do site.

Repare em dois detalhes do exemplo acima. A mensagem de commit começa com a área afetada seguida de uma descrição curta no imperativo, que é o estilo esperado no projeto, e a flag de assinatura no commit é uma boa prática incentivada. Commits limpos e atômicos facilitam demais a vida de quem vai revisar, e facilitar o review é literalmente a melhor forma de fazer o seu PR avançar mais rápido.

Como abrir um pull request?

Um pull request no Bitcoin Core não é só um pacote de código, ele é um argumento. Você precisa convencer pessoas experientes e ocupadas de que a sua mudança vale o tempo de review delas, então a descrição importa quase tanto quanto o diff. Antes de abrir, vale reler as orientações no guia de contribuição do projeto e no documento de developer notes, que trazem o estilo de código e as convenções esperadas.

Aqui vão algumas orientações para você abrir o seu primeiro pull request no github do Bitcoin Core:

• Explique o problema que você está resolvendo e por que ele importa, não apenas o que o código faz.
• Mantenha o PR pequeno e focado em uma única mudança, porque PRs gigantes quase nunca são revisados.
• Inclua testes que provem que a sua mudança funciona e que ela não quebra o comportamento existente.
• Siga o estilo de código do projeto à risca, já que divergências de estilo travam o review por detalhes.
• Responda os comentários de review com humildade e rapidez, tratando cada feedback como uma oportunidade de melhorar.
• Evite reescrever histórico de forma confusa, e quando precisar refazer commits explique o que mudou entre as versões.

Uma mentalidade que ajuda muito é entender que o seu PR provavelmente vai mudar bastante entre a abertura e o merge. Isso não é sinal de fracasso, é o processo funcionando. Cada rodada de review deixa a mudança mais segura, e quem encara o feedback como colaboração em vez de crítica pessoal cresce muito mais rápido dentro do projeto.

O processo de code review e a linguagem dos ACKs

O code review é onde o Bitcoin Core realmente acontece, e ele tem uma linguagem própria que confunde quem está chegando. Os revisores deixam comentários no PR e, conforme o nível de análise que fizeram, registram diferentes tipos de aprovação ou objeção. Entender exatamente o que cada termo significa é o que separa quem participa de verdade de quem fica perdido na conversa.

Nessa tabela abaixo a gente explica os termos para que você entenda cada um deles:

Termo	O que significa
Concept ACK	Concordo com a ideia e com o problema que o PR resolve, ainda sem ter revisado o código a fundo.
Approach ACK	Concordo com a abordagem técnica escolhida para resolver o problema, além do conceito.
ACK / tested ACK	Revisei o código, ele me parece correto e, no caso do tested ACK, também testei na prática.
utACK	Untested ACK, ou seja, revisei o código e concordo, mas não rodei os testes localmente.
NACK	Sou contra a mudança, e o esperado é sempre explicar o motivo técnico da objeção.
nit	Comentário menor sobre estilo ou detalhe que não bloqueia o merge, mas seria bom ajustar.

Esses ACKs não são votos no sentido democrático, eles são sinais de confiança técnica que os mantenedores usam para decidir se uma mudança está madura. Um PR com vários tested ACKs de revisores respeitados tem muito mais chance de ser mesclado, e é por isso que a reputação de quem revisa bem vale tanto quanto a de quem escreve bem.

Para ver como tudo isso funciona ao vivo, vale acompanhar o PR Review Club do Bitcoin Core, que é um encontro semanal aberto em que a comunidade revisa um pull request específico em conjunto. É de longe a melhor forma de aprender a revisar de verdade, porque você vê desenvolvedores experientes pensando em voz alta sobre código real do projeto.

Como revisar PRs e por que isso é a contribuição mais valiosa

Existe um desequilíbrio crônico no Bitcoin Core, sempre tem muito mais código sendo proposto do que gente disposta a revisar com cuidado. Isso significa que, se você quer ser útil de imediato e construir reputação no projeto, revisar pull requests dos outros é o caminho mais rápido e mais valorizado. Você não precisa esperar ter o seu próprio PR perfeito para começar a contribuir, pode começar revisando hoje.

Como revisar PRs:

• Escolha um PR dentro de uma área que você conhece e leia a descrição e a discussão inteira antes de opinar.
• Baixe a branch, compile e rode os testes, porque um tested ACK vale muito mais que um comentário superficial.
• Comece pelo conceito, deixe um Concept ACK ou aponte por que a ideia pode não fazer sentido.
• Seja específico nos comentários, aponte a linha exata e explique o raciocínio em vez de só dizer que está errado.
• Trate o autor com respeito, lembrando que do outro lado tem uma pessoa que dedicou tempo para melhorar o Bitcoin.

Revisar bem também te ensina a escrever PRs melhores, porque você passa a enxergar o código pela ótica de quem precisa entendê-lo e confiar nele. Com o tempo, a sua opinião começa a ter peso, os mantenedores passam a te reconhecer e o caminho para contribuições maiores e mais importantes se abre naturalmente.

Boas práticas e erros comuns de quem está começando

Quase todo mundo comete os mesmos erros nas primeiras contribuições, e conhecê-los de antemão economiza muita frustração. O erro mais comum é querer começar grande, com mudanças polêmicas de consenso ou refatorações enormes que ninguém pediu. O segundo é desaparecer depois de abrir o PR, sem responder aos reviews, o que faz o trabalho morrer parado. O terceiro é levar o feedback técnico para o lado pessoal.

Aqui está uma lista de boas práticas:

• Não comece por mudanças de consenso, que são as mais sensíveis e exigem anos de contexto.
• Não abra PRs gigantes, porque eles são quase impossíveis de revisar e raramente avançam.
• Não suma depois de abrir o PR, acompanhe e responda os comentários com regularidade.
• Não ignore os testes nem o estilo de código, já que são os primeiros motivos de um PR ser barrado.
• Não trate NACK como ataque, e sim como informação técnica que pode estar te poupando de um erro.
• Não tenha pressa, porque a paciência é literalmente parte da engenharia de segurança do Bitcoin.

Além do código, outras formas de contribuir

Se você ainda não se sente pronto para mexer no C++ do node, existem várias formas legítimas e necessárias de contribuir desde já. Testar mudanças propostas e relatar os resultados, melhorar a documentação e os comentários do código, reportar bugs com passos claros de reprodução, ajudar na tradução e escrever sobre propostas como o RBF e o Erlay são contribuições que fortalecem o ecossistema inteiro. Inclusive estudar e explicar conceitos como o Bitcoin Script e o SegWit na prática ajuda a formar a próxima geração de revisores.

No fim das contas, contribuir com o Bitcoin é construir sobre a base lançada pelo whitepaper do Bitcoin, e cada revisão cuidadosa, cada teste rodado e cada linha de documentação melhorada faz parte desse esforço coletivo de manter o dinheiro mais sólido do mundo funcionando para todos.

Perguntas frequentes sobre contribuir com o Bitcoin Core

Preciso saber programar para contribuir com o Bitcoin Core?

Não necessariamente. Embora o código seja em C++, você pode contribuir revisando pull requests, testando mudanças, melhorando documentação, reportando bugs e ajudando em traduções. Essas contribuições são muito valorizadas e costumam estar em falta no projeto, então existe espaço para ser útil mesmo sem escrever código no começo.

Qual linguagem o Bitcoin Core usa?

O Bitcoin Core é escrito principalmente em C++ moderno, com partes de Python usadas na suíte de testes funcionais e scripts de apoio. Dominar C++, Git e o fluxo de trabalho do GitHub é o conjunto de pré-requisitos mais importante para quem quer contribuir com código.

O que é uma good first issue no Bitcoin Core?

Uma good first issue é uma tarefa marcada pelos mantenedores como adequada para quem está começando, geralmente pequena e bem delimitada. Elas ficam reunidas na página de contribuição do repositório no GitHub e são o melhor ponto de partida para a sua primeira contribuição.

O que significam ACK e NACK em um pull request?

ACK significa que o revisor concorda com a mudança, e existem variações como Concept ACK para a ideia, Approach ACK para a abordagem e tested ACK quando o revisor também testou o código. NACK significa que o revisor é contra a mudança e deve explicar o motivo técnico da objeção. Esses sinais ajudam os mantenedores a decidir se um PR está maduro para ser mesclado.

Quanto tempo leva para um pull request ser aceito?

Não há prazo fixo e é completamente normal um pull request levar semanas ou meses para ser mesclado. O Bitcoin Core é conservador por design, então a revisão cuidadosa e demorada faz parte da engenharia de segurança do projeto. Começar com mudanças pequenas e responder rápido aos reviews acelera bastante o processo.

Por onde devo começar se nunca contribuí com Bitcoin Core?

Comece compilando o Bitcoin Core localmente, leia pull requests recentes para entender a cultura, escolha uma good first issue e participe de revisões de outras pessoas. Acompanhar o PR Review Club da comunidade também é uma das formas mais rápidas de aprender a revisar e contribuir de verdade.

Conclusão

Contribuir com o Bitcoin Core é uma das formas mais profundas de se envolver com o Bitcoin, porque você deixa de apenas usar a rede e passa a fazer parte da engenharia que a mantém viva e segura. O processo é exigente de propósito, mas ele é totalmente aberto, e qualquer pessoa disposta a estudar, começar pequeno, revisar com cuidado e respeitar a cultura do projeto pode chegar lá. Não existe permissão a pedir, existe apenas trabalho a fazer.

Se você quer trilhar esse caminho com método e em comunidade, comece pelo Bitcoin Coders, a escola técnica gratuita da Area Bitcoin, e construa a base que vai te levar do primeiro git clone até o seu primeiro pull request.

Até o próximo artigo e opt out!

Compartilhe em suas redes sociais:

Escrito por

Area Bitcoin

A maior escola de educação sobre Bitcoin do mundo, que tem como objetivo elevar o conhecimento da comunidade e dos bitcoiners de todo o mundo aos níveis mais altos de soberania financeira, intelectual e tecnológica.

Curtiu esse artigo? Considere nos pagar um cafezinho para continuarmos escrevendo novos conteúdos! ☕