guides

O Versionamento Semântico, quase sempre abreviado como SemVer, é um conjunto simples de regras para numerar lançamentos de software de modo que o próprio número de versão diga o que mudou. Em vez de um contador sem significado, uma versão SemVer é composta por três números, MAJOR.MINOR.PATCH, como 2.4.1, e cada posição tem um significado definido. Assim que você conhece as regras, consegue olhar para um aumento de versão e entender imediatamente se uma atualização é segura, adiciona funcionalidades ou pode quebrar o seu código.

As três partes respondem, cada uma, a uma pergunta diferente. MAJOR (o primeiro número) aumenta quando você faz alterações incompatíveis e que quebram a API pública, e atualizar pode exigir que você mude o seu próprio código. MINOR (o segundo) aumenta quando você adiciona novas funcionalidades de forma retrocompatível, ou seja, novos recursos que você pode adotar ou ignorar. PATCH (o terceiro) aumenta em correções de bugs retrocompatíveis, correções seguras que não mudam a forma como o software é usado.

Há duas regras mecânicas que confundem as pessoas. Quando você aumenta o MAJOR, você zera MINOR e PATCH: depois de 1.4.2, uma alteração que quebra a compatibilidade torna-se 2.0.0, e não 2.4.2. Quando você aumenta o MINOR, você zera o PATCH: depois de 1.4.2, uma nova funcionalidade torna-se 1.5.0. Portanto, os números à direita sempre recomeçam quando um número à sua esquerda sobe.

O SemVer também tem uma regra especial para o desenvolvimento inicial. Qualquer versão que comece com 0, como 0.3.1, é considerada instável, e as garantias normais não se aplicam totalmente. Durante o 0.x, a API pode mudar a qualquer momento, então trate esses lançamentos com cautela. O salto para 1.0.0 é um sinal deliberado: significa que o autor está se comprometendo com uma API pública estável e com seguir as regras do SemVer a partir de então.

Além dos três números centrais, o SemVer suporta rótulos de pré-lançamento e de build. Uma versão de pré-lançamento adiciona um hífen e um identificador, como 1.0.0-alpha, 1.0.0-beta.2 ou 1.0.0-rc.1, e tem precedência menor do que o lançamento final, de modo que 1.0.0-rc.1 vem antes de 1.0.0. Os metadados de build podem ser adicionados após um sinal de mais, como 1.0.0+20260715, mas são ignorados na comparação de versões. Isso permite que as equipes publiquem builds de teste sem fingir que são lançamentos finalizados.

A razão pela qual tudo isso importa é o gerenciamento de dependências. Quando o seu projeto depende de uma biblioteca, você raramente fixa uma versão exata para sempre; você permite um intervalo. Os gerenciadores de pacotes usam o SemVer para tornar esses intervalos seguros. No npm, por exemplo, um intervalo com circunflexo como ^1.2.3 significa qualquer versão a partir de 1.2.3 até, mas sem incluir, 2.0.0, ou seja, todas as atualizações retrocompatíveis e nenhuma das que quebram a compatibilidade. Um intervalo com til como ~1.2.3 é mais restrito, permitindo atualizações de patch até, mas sem incluir, 1.3.0.

Esses intervalos só funcionam porque todos concordam sobre o que significa um aumento de versão. Se uma biblioteca publica uma alteração que quebra a compatibilidade mas apenas incrementa o PATCH, ela pode quebrar silenciosamente todos os projetos que confiaram no intervalo. Esse é o contrato social no coração do SemVer: o número é uma promessa sobre compatibilidade, e honrá-lo é o que impede que todo o ecossistema de atualizações automáticas desmorone.

O SemVer é definido por uma especificação curta e legível em semver.org, e é o esquema usado pelo npm, pelo Cargo e por inúmeros outros registros e ferramentas de pacotes. Não é a única maneira de versionar software, alguns projetos usam versionamento por calendário (como 2026.07) ou o seu próprio esquema, mas o SemVer é o mais amplamente compreendido, e conhecê-lo torna muito mais fácil ler changelogs e intervalos de dependências.

A lição prática: leia uma versão como uma frase. Um aumento no primeiro número diz para parar e verificar se há alterações que quebram a compatibilidade antes de atualizar. Um aumento no segundo diz que há novas funcionalidades, mas o seu código existente está seguro. Um aumento no terceiro diz que é uma correção de bug segura. Esse único hábito, ler a posição que mudou, transforma um número opaco em uma mensagem clara sobre risco.