Versionamento semântico: o que é e como aplicar na prática

Versionamento semântico, também conhecido como SemVer (abreviação de Semantic Versioning), é um padrão de numeração de versões que indica o grau de compatibilidade entre releases de um software. O formato segue a estrutura MAJOR.MINOR.PATCH, onde cada número carrega um significado específico sobre o tipo de mudança introduzida. O objetivo é eliminar o dependency hell, a confusão gerada por versões que não comunicam claramente se uma atualização quebra ou não o código existente. Segundo a especificação oficial mantida pela comunidade (semver.org), a regra básica é: incremente MAJOR quando fizer mudanças incompatíveis na API; MINOR quando adicionar funcionalidades retrocompatíveis; e PATCH quando corrigir bugs retrocompatíveis.

Como funciona o formato MAJOR.MINOR.PATCH?

Cada segmento do número de versão tem uma função. O PATCH (terceiro dígito) aumenta quando você corrige um bug sem alterar o comportamento público da API. O MINOR (segundo dígito) sobe quando você adiciona uma nova funcionalidade que não quebra o código existente. O MAJOR (primeiro dígito) é incrementado quando uma mudança quebra a compatibilidade com versões anteriores. Exemplo prático: da versão 1.3.7 para 1.4.0 há adição de funcionalidade; de 1.4.0 para 2.0.0 há quebra de compatibilidade.

O que significa o zero inicial (0.x.x)?

Versões começando com 0 (ex.: 0.1.0) indicam que o software está em desenvolvimento inicial. A especificação SemVer trata a versão 0.x.x como instável, qualquer mudança pode quebrar a API a qualquer momento, sem aviso. Por isso, ao depender de um pacote na faixa 0.x, o desenvolvedor deve esperar instabilidade. O primeiro release estável é o 1.0.0.

Como aplicar versionamento semântico na prática?

Para aplicar o SemVer, comece definindo uma API pública, mesmo que informal. Toda mudança que afete essa API deve refletir no número de versão. Ferramentas como npm (Node.js), Composer (PHP) e PyPI (Python) já usam SemVer como padrão. Use tags no Git (ex.: v1.2.3) para marcar cada release. Nunca altere uma versão já publicada: se precisar corrigir algo, publique um novo PATCH. A transparência nas mudanças é o princípio central.

Quando devo usar pré-release (ex.: 1.0.0-alpha)?

Pré-releases são indicados por um hífen após o PATCH, seguido de um identificador (ex.: 1.0.0-alpha.1, 2.0.0-beta). Eles sinalizam que a versão ainda não é estável, mas já está disponível para testes. A precedência entre pré-releases é determinada pela ordem alfabética e numérica dos identificadores. Uma versão de pré-release tem menor prioridade que a versão normal correspondente, ou seja, 1.0.0-alpha < 1.0.0.

Qual a diferença entre versionamento semântico e versionamento sequencial?

No versionamento sequencial (ex.: 1.0, 2.0, 3.0), o número subjetivo não comunica o tipo de mudança. Já o SemVer codifica a compatibilidade no próprio número: um salto de MAJOR informa quebra de API; MINOR informa adição compatível; PATCH informa correção. Isso permite que gerenciadores de dependência (como npm e Bundler) determinem automaticamente se uma atualização é segura.

Resumo prático

Versionamento semântico é um contrato entre o desenvolvedor e quem consome o software. Adotar o SemVer significa comunicar de forma clara e previsível o impacto de cada nova versão. Comece definindo sua API, use o formato MAJOR.MINOR.PATCH, e respeite as regras de incremento. O resultado é um ecossistema de dependências mais confiável e menos sujeito a quebras inesperadas.

Perguntas frequentes sobre versionamento semântico

Posso começar a usar SemVer em um projeto já existente?

Sim. A partir do próximo release, defina a versão atual como base e aplique as regras. Se o projeto já tem dependentes, considere marcar o estado atual como 1.0.0 e seguir adiante.

O que fazer se uma correção de bug quebrar a API?

Isso não deveria ocorrer. Se acontecer, a correção não é um PATCH, é uma mudança MAJOR. Documente a quebra e publique como nova versão MAJOR.

Como versionar documentação que não tem API?

Documentação sem API pública não precisa de SemVer. Use versionamento sequencial ou datas. O SemVer só faz sentido quando há uma interface que outros sistemas consomem.

O SemVer funciona para aplicações web (frontend)?

Sim, desde que a aplicação exponha uma API (ex.: biblioteca JavaScript). Para apps que não são bibliotecas, o versionamento semântico perde o sentido, pois não há consumidores de API.

Qual a diferença entre ~ e ^ no npm?

No npm, o til (~) permite atualizações apenas de PATCH (ex.: ~1.2.3 aceita 1.2.4). O circunflexo (^) permite atualizações de MINOR (ex.: ^1.2.3 aceita 1.3.0). Ambos respeitam SemVer.

Uma versão 1.0.0 pode ter pré-release?

Sim, desde que o pré-release seja aplicado a uma versão futura. Ex.: 1.0.0 é estável; 1.1.0-alpha.1 é um pré-release da próxima MINOR.