Versionamento semântico (SemVer): o que é e como usar

Versionamento semântico (SemVer) é um conjunto de regras que padroniza os números de versão de um software no formato MAJOR.MINOR.PATCH. Cada parte comunica o tipo de mudança — quebra de compatibilidade, nova função ou correção de bug — revelando o impacto de atualizar uma dependência antes de ler o changelog.

• O que é versionamento semântico (SemVer)?
• Por que o versionamento semântico existe?
• Como funciona o formato MAJOR.MINOR.PATCH?
• Quais regras o SemVer define para publicar versões?
• O que são as fases Alpha e Beta no ciclo de lançamento?
• Como aplicar versionamento semântico no Git e GitHub?

O que é versionamento semântico (SemVer)?

O versionamento semântico é um padrão que atribui significado a cada número de uma versão de software, no formato MAJOR.MINOR.PATCH (por exemplo, 2.4.1). Em vez de um número arbitrário, cada dígito carrega uma promessa sobre o que mudou desde o release anterior.

A especificação de referência é a SemVer 2.0.0, escrita por Tom Preston-Werner, cofundador do GitHub, e publicada em semver.org. Ela resume as três regras centrais assim: incremente a versão MAJOR em mudanças incompatíveis na API (Application Programming Interface), a MINOR ao adicionar funcionalidades de forma compatível e a PATCH em correções de bugs compatíveis.

O modelo é intencionalmente simples: com três números, qualquer desenvolvedor entende o risco de uma atualização sem precisar ler o histórico completo do projeto. É essa clareza que torna o SemVer o padrão de fato para bibliotecas de código aberto.

Por que o versionamento semântico existe?

O SemVer nasceu para resolver um problema concreto: o chamado inferno de dependências. Ele acontece quando atualizar uma biblioteca quebra outras que dependiam de comportamentos antigos, gerando conflitos de versão em cascata que travam um projeto inteiro.

Se você já instalou pacotes, frameworks ou softwares, notou a sequência numérica que indica a versão atual. Essa sequência é crucial para entender mudanças, melhorias e possíveis incompatibilidades. Sem uma convenção compartilhada, cada projeto numeraria releases à sua maneira, e ferramentas automáticas não teriam como decidir se uma atualização é segura.

A escala do problema é enorme. Um estudo de larga escala da NPM conduzido por Pinckney e colegas (2023) analisou todas as versões de todos os pacotes de um registro com mais de dois milhões de bibliotecas e dezenas de bilhões de downloads semanais, e concluiu que, quando o SemVer é bem aplicado, patches de segurança chegam rapidamente às dependências em 90,09% dos casos (arXiv:2304.00394). O número mostra o quanto ecossistemas inteiros dependem dessa convenção para propagar correções críticas.

Como funciona o formato MAJOR.MINOR.PATCH?

O formato do versionamento semântico é dividido em três partes, incrementadas segundo o tipo de mudança introduzida na API pública. A tabela abaixo resume o que cada incremento significa na prática:

Repare que, ao incrementar um dígito, os que estão à sua direita voltam a zero: uma nova MINOR zera o PATCH, e uma nova MAJOR zera MINOR e PATCH.

MAJOR: quando quebra a compatibilidade

O primeiro dígito informa mudanças que tornam o software incompatível com versões anteriores — as breaking changes. Renomear uma função pública, remover um parâmetro ou alterar o formato de retorno de uma API são exemplos clássicos que exigem subir a MAJOR.

MINOR: quando adiciona funcionalidades

O segundo dígito se refere a novas funcionalidades ou melhorias que não afetam a compatibilidade. Quem já usava a versão anterior pode atualizar sem alterar seu código; apenas ganha novos recursos opcionais.

PATCH: quando corrige bugs

O terceiro dígito cobre correções de bugs e melhorias de desempenho que não alteram funcionalidades existentes. É a atualização mais segura de aplicar, e a que gerenciadores de pacotes costumam instalar automaticamente.

Quais regras o SemVer define para publicar versões?

O versionamento semântico não é só sobre números e pontos: ele estabelece regras claras para garantir que todos entendam o que cada versão significa. Três delas são essenciais para publicar releases de forma confiável:

1. Estrutura X.Y.Z — toda versão segue o formato X.Y.Z, onde X é a MAJOR, Y é a MINOR e Z é a PATCH. Os números são inteiros não negativos e não devem conter zeros à esquerda (use 1.2.0, nunca 1.02.0).
2. Incremento lógico — as versões avançam de forma sequencial. Não se pula de 1.0.0 direto para 3.0.0 sem passar por 2.0.0; cada release incrementa exatamente um dígito.
3. Imutabilidade — uma vez publicada, uma versão nunca é alterada. Segundo a especificação oficial, "Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version."

A imutabilidade é o que garante que 1.4.2 signifique sempre o mesmo código, em qualquer máquina e em qualquer data — a base para builds reproduzíveis.

O que são as fases Alpha e Beta no ciclo de lançamento?

Antes de chegar a um release estável, o software costuma passar por fases de pré-lançamento que o SemVer permite marcar com um sufixo (por exemplo, 1.0.0-alpha ou 1.0.0-beta.2). Essas fases sinalizam que a versão ainda não é considerada pronta para produção.

Versão Alpha

A versão Alpha é a primeira testada pelos times de desenvolvimento e geralmente não é publicada para o público geral. O foco é validar a estabilidade e caçar bugs graves antes de uma exposição maior.

Versão Beta

Após a Alpha vem a Beta, primeira versão pública do software. Aqui os usuários têm papel crucial: testam o produto em cenários reais e fornecem feedback que orienta os ajustes finais rumo à versão estável 1.0.0.

Como aplicar versionamento semântico no Git e GitHub?

No fluxo de controle de versão com Git e GitHub, o versionamento semântico se materializa em tags e releases. É assim que uma equipe registra, de forma permanente, qual commit corresponde a cada número de versão publicado. Ferramentas como npm e outros gerenciadores de pacotes leem exatamente essas versões para resolver dependências.

Vale reforçar como a documentação do npm resume a progressão: comece em 1.0.0; incremente o último dígito em correções, o do meio em novos recursos e o primeiro em mudanças que quebram a compatibilidade (npm Docs).

O que são tags e releases?

As tags no Git representam pontos específicos na história do código que correspondem a uma versão. Os releases são descrições públicas dessas tags, onde você comunica novidades, correções e mudanças de cada versão — o changelog que os usuários realmente leem.

Como criar sua primeira tag no Git?

Para transformar um commit em uma versão publicável, siga estes passos:

1. Abra o terminal na raiz do repositório e confirme que o commit desejado está no histórico com git log --oneline.
2. Crie uma tag anotada com o número da versão: git tag -a v1.0.0 -m "Primeira versão estável".
3. Confira se a tag foi criada corretamente com git tag ou git show v1.0.0.
4. Envie a tag ao repositório remoto com git push origin v1.0.0 (ou git push --tags para enviar todas de uma vez).

Depois disso, no GitHub, basta abrir a tag e publicar um release com as notas da versão — e sua biblioteca passa a falar a mesma língua de todo o ecossistema.

Conclusão

Adotar versionamento semântico é uma das decisões de menor custo e maior retorno que uma equipe pode tomar. Com três números você transforma cada release em uma promessa explícita sobre compatibilidade, elimina boa parte do inferno de dependências e permite que ferramentas automatizem atualizações com segurança. Aqui no CodeCrush, a recomendação é simples: comece a versionar em 1.0.0 no seu próximo projeto, seja rigoroso ao subir a MAJOR quando quebrar algo, e trate cada número como um contrato com quem usa o seu código.