O que é bump2version em Rust

bump2version é uma ferramenta para automatizar o versionamento de projetos. Ela encontra a versão atual, calcula a próxima versão e aplica a mudança nos arquivos que você indicar, evitando editar o mesmo número manualmente em vários lugares.

O projeto apresentado nesta matéria tem um núcleo escrito em Rust e oferece uma CLI, um crate Rust e integrações nativas para Python e Node.js. A versão demonstrada no artigo de referência é a 0.2.0, disponível no repositório oficial da conta wiseaidev.

A ferramenta ganhou atenção por combinar automação de release com uma implementação compilada. O ponto não é apenas trocar 1.4.2 por 1.4.3, mas manter Cargo.toml, package.json, pyproject.toml, CHANGELOG.md e outros arquivos sincronizados em um único fluxo revisável.

Como funciona

O bump2version lê uma configuração e interpreta a versão com uma expressão regular configurável. O padrão segue o formato semver, com componentes major, minor e patch, mas a configuração também pode representar estágios personalizados, como alpha, beta e stable.

Depois do parse, a ferramenta calcula o próximo valor e substitui ocorrências nos arquivos selecionados. Os marcadores {current_version} e {new_version} permitem descrever exatamente o trecho que deve ser procurado e o trecho que deve entrar no lugar.

Quando o fluxo inclui commit ou tag, o projeto usa a biblioteca gix, também conhecida como gitoxide, para operar com Git sem depender de chamadas a subprocessos. O cache de expressões regulares compartilhado entre threads evita recompilar o mesmo padrão em cada operação.

Principais recursos

A CLI permite escolher a parte da versão, apontar um arquivo de configuração, informar uma versão atual ou nova e executar um dry run. Isso ajuda a revisar a alteração antes de tocar no working tree.

O mesmo núcleo pode ser usado como crate Rust, pacote Python ou add-on de Node.js. Assim, a regra de versionamento pode ficar centralizada mesmo quando um repositório tem scripts em linguagens diferentes.

  • Vários arquivos: atualize manifestos, changelogs e documentação na mesma operação.
  • Estágios customizados: modele ciclos como alpha, beta, rc e stable.
  • Git integrado: crie commit e tag quando essa opção fizer parte da configuração.
  • no_std: os módulos centrais podem compilar com no_std e alloc.

Como começar: instalação ou acesso passo a passo

Primeiro, escolha a forma de integração. Para usar o binário, você precisará do toolchain Rust e do Cargo. Para chamar o núcleo a partir de Python, use o pacote bump-rs. Em Node.js, instale o pacote bump2version pelo npm.

cargo install bump2version --features rust-binary
pip install bump-rs
npm install bump2version

Em seguida, crie um arquivo .bumpversion.toml na raiz do projeto. Comece com um único manifesto e um changelog pequeno, valide o resultado e só depois inclua outros arquivos no padrão.

[bumpversion]
current_version = '1.4.2'
commit = true
tag = true

[bumpversion:file:Cargo.toml]
search = 'version = "{current_version}"'
replace = 'version = "{new_version}"'

[bumpversion:file:CHANGELOG.md]
search = '## {current_version}'
replace = '## {new_version}'

Por fim, confira a documentação oficial da integração escolhida. A CLI, o crate Rust e os bindings têm responsabilidades diferentes, então a instalação correta depende de onde a regra será executada.

Exemplo prático

Imagine um projeto Rust na versão 1.4.2. O número aparece no Cargo.toml e no topo do CHANGELOG.md. Com a configuração anterior, o comando de teste calcula 1.4.3 e mostra quais arquivos seriam afetados.

bump2version --config-file .bumpversion.toml --bump patch --dry-run
bump2version --config-file .bumpversion.toml --bump patch

No primeiro comando, o dry run serve para revisar a operação. No segundo, a configuração permite atualizar o manifesto e o changelog e, se as opções estiverem ativas, criar um commit e uma tag correspondentes.

Antes de enviar a alteração, confirme o diff e o estado do Git. Um bom resultado é aquele em que todos os arquivos esperados foram alterados, nenhum arquivo inesperado foi tocado e a suite do projeto continua passando.

💡
Dica

Comece com --dry-run em uma branch de teste. O versionador só é confiável quando o padrão de busca não captura números que não representam a versão do projeto.

Comparação com alternativas

O bump-my-version continua sendo uma opção natural para quem já vive no ecossistema Python e quer uma ferramenta familiar. A escolha fica simples quando o time prioriza compatibilidade com o fluxo existente em vez de compartilhar um núcleo entre linguagens.

Um script curto em Python pode ser suficiente para um repositório que altera um único arquivo. Ele tende a ser mais fácil de adaptar, mas exige que o próprio time cuide de validação, múltiplas ocorrências, changelog e integração com Git.

Ferramentas de automação de release mais amplas podem cuidar de publicação, changelog, CI e distribuição. O bump2version tem um escopo menor: seu ponto forte é fazer o versionamento de arquivos de forma consistente, com uma implementação Rust reutilizável em diferentes ecossistemas.

  • Use bump2version: quando vários arquivos e linguagens precisam seguir a mesma versão.
  • Use um script: quando a regra é pequena, local e fácil de testar.
  • Use uma plataforma de release: quando o problema inclui publicação, notas e orquestração de CI.

Pontos positivos e limitações

Entre os pontos positivos estão a configuração explícita, a integração com Rust, Python e Node.js e a possibilidade de atualizar vários arquivos de uma vez. O suporte no_std nos módulos centrais também pode interessar a projetos com restrições específicas de ambiente.

O próprio benchmark publicado pelo autor precisa ser lido com contexto. A comparação foi feita em x86-64 Linux com CPython 3.12 e mostrou cerca de 57 microssegundos para bump-rs contra cerca de 585 milissegundos para a CLI Python comparada, mas uma chamada isolada de Python puro pode ser mais rápida quando o custo de FFI domina.

Há outras limitações práticas. Você precisa escrever uma configuração correta, o projeto ainda lista recursos como suporte a workspace como roadmap e a camada FFI do add-on Node.js tem uma exceção de segurança necessária para a interoperabilidade do napi-rs. O resultado deve ser medido no seu repositório, não aceito apenas pelo número do título.

⚠️
Atenção

Não compare apenas o tempo de trocar uma string. Em um release real entram leitura de arquivos, validação, testes, commit, tag e CI.

Casos de uso reais

Uma equipe Rust pode usar a CLI para manter Cargo.toml, changelog e documentação alinhados antes de publicar uma nova versão. A configuração fica revisável no próprio repositório e o dry run reduz surpresas no release.

Um projeto Python com componentes nativos pode chamar o pacote bump-rs em um script de automação. O time mantém a lógica de versionamento perto do código Python sem voltar a executar uma CLI externa para cada alteração.

Uma biblioteca JavaScript com um módulo Rust pode compartilhar a mesma ideia de versão entre package.json, arquivos de documentação e artefatos do projeto. O add-on de Node.js é útil quando a atualização precisa acontecer dentro do fluxo JavaScript.

Também há espaço para projetos embarcados que usam os módulos centrais. O suporte no_std não transforma a ferramenta em um sistema completo de release para qualquer microcontrolador, mas permite avaliar o núcleo em um ambiente com menos recursos.

Dicas e boas práticas

Trate o arquivo de configuração como código. Faça revisão por pull request, mantenha os padrões de busca específicos e escreva um teste que confirme a versão esperada depois da substituição.

💡
Dica

Use placeholders de versão em vez de uma substituição global. Isso evita alterar exemplos, números de dependências ou textos que apenas parecem uma versão.

🚀
Pro tip

Quando o projeto tem vários pacotes, separe a etapa de calcular a nova versão da etapa de publicar. Assim, a mesma mudança pode ser validada no CI antes de criar uma tag.

⚠️
Atenção

Fixe a versão da ferramenta no ambiente de CI e registre a versão usada no log. Uma atualização automática pode mudar o comportamento do parser ou das opções da CLI.

🔴
Cuidado

Não execute um bump sem revisar o diff. Um padrão amplo demais pode alterar arquivos de produção, gerar uma tag errada e espalhar uma versão incorreta para o pacote.

Vale a pena?

Vale a pena testar o bump2version quando seu projeto repete o mesmo número em manifestos, changelogs e bindings de linguagens diferentes. A combinação de configuração explícita e núcleo Rust resolve um problema pequeno, mas recorrente, sem exigir uma plataforma inteira de release.

Para um repositório com uma única versão em um único arquivo, um script simples pode ser mais direto. Para quem precisa de workspace, publicação e notas totalmente orquestrados, será necessário complementar a ferramenta ou escolher uma solução de release mais ampla.

O próximo passo é clonar o repositório oficial, criar uma configuração mínima e testar o dry run em uma branch. Se o diff sair exatamente como esperado e o CI confirmar a mudança, aí sim vale conectar o comando ao fluxo de release.