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

> Versionamento semântico é um padrão de numeração de versões no formato MAJOR.MINOR.PATCH. A versão MAJOR incrementa com mudanças incompatíveis, MINOR com novas funcionalidades compatíveis e PATCH com correções de bugs. A aplicação prática exige seguir essas regras para comunicar claramente o impacto de cada release, garantindo previsibilidade e compatibilidade entre dependências de software.

*Net Propaganda · Apps e Software · 19 de julho de 2026 · Ptolomeu Rangel Sicupira*

Versionamento semântico é um padrão de numeração de versões que comunica o nível de compatibilidade entre releases. Saiba como aplicar as regras MAJOR.MINOR.PATCH.

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

---

Fonte (canonical): https://netpropaganda.com.br/apps-e-software/versionamento-semantico-o-que-e-e-como-aplicar-na-pratica/