Neste artigo
O que e versionamento semantico?
O Versionamento Semântico (SemVer) é um esquema de versionamento que atribui significado a cada parte de um número de versão. Criado por Tom Preston-Werner, o SemVer fornece uma convenção universal para comunicar a natureza e o impacto das mudanças de software apenas pelos números de versão.
Ao seguir o SemVer, desenvolvedores e usuários podem entender instantaneamente se uma atualização introduz mudanças incompatíveis, novos recursos ou correções de bugs — apenas lendo o número de versão. Essa previsibilidade é crucial para o gerenciamento de dependências nos ecossistemas de software modernos.
O formato SemVer
Uma versão semântica consiste em três componentes numéricos separados por pontos: MAJOR.MINOR.PATCH.
- MAJOR — incrementado quando são feitas mudanças incompatíveis na API. Ir de 1.x.x para 2.0.0 sinaliza que o código existente pode quebrar
- MINOR — incrementado quando funcionalidades são adicionadas de forma compatível com versões anteriores. Ir de 1.2.x para 1.3.0 significa novos recursos sem quebrar os existentes
- PATCH — incrementado quando são feitas correções de bugs compatíveis com versões anteriores. Ir de 1.2.3 para 1.2.4 significa que apenas bugs foram corrigidos
- Cada componente deve ser um inteiro não negativo e não deve conter zeros à esquerda (1.02.3 é inválido)
Experimente gratuitamente — sem cadastro
Validar uma versao SemVer →Intervalos de versao
Os gerenciadores de pacotes usam intervalos de versão para especificar versões de dependência compatíveis. Compreender esses intervalos é essencial para builds confiáveis.
- Intervalos caret (^1.2.3) — permitem mudanças que não modificam o dígito mais à esquerda diferente de zero. ^1.2.3 significa qualquer versão de 1.2.3 até, mas não incluindo, 2.0.0
- Intervalos tilde (~1.2.3) — permitem apenas mudanças no nível de patch. ~1.2.3 significa qualquer versão de 1.2.3 até, mas não incluindo, 1.3.0
- Versão exata (1.2.3) — somente essa versão específica é aceitável, sem flexibilidade
Casos de uso
O versionamento semântico é a base do gerenciamento de pacotes moderno e dos fluxos de trabalho de lançamento.
- npm, pip e Cargo — os gerenciadores de pacotes dependem do SemVer para resolver árvores de dependência e evitar que mudanças incompatíveis cheguem à produção
- Pipelines CI/CD — sistemas automatizados usam tags SemVer para acionar builds, publicar lançamentos e gerar changelogs
- Versionamento de API — APIs REST usam versões principais nas URLs (v1, v2) para manter a compatibilidade com versões anteriores enquanto evoluem
- Autores de bibliotecas — publicar uma biblioteca com SemVer adequado sinaliza aos consumidores quando as atualizações são seguras
Pre-release e metadados
O SemVer suporta duas extensões opcionais que adicionam contexto aos números de versão sem afetar as regras de precedência.
- Identificadores de pré-lançamento — adicionados após um hífen: 1.0.0-alpha, 1.0.0-beta.2, 1.0.0-rc.1. Estes indicam versões que ainda não são estáveis e têm precedência menor do que o lançamento associado
- Metadados de build — adicionados após um sinal de mais: 1.0.0+build.123, 1.0.0-beta+exp.sha.5114f85. Os metadados de build são ignorados ao determinar a precedência de versão
- As versões de pré-lançamento são ordenadas usando identificadores separados por pontos: identificadores numéricos são ordenados numericamente, identificadores alfanuméricos são ordenados lexicalmente
FAQ
O 0.x.x é tratado de forma diferente do 1.x.x?
Sim. No SemVer, a versão 0.x.x indica desenvolvimento inicial onde qualquer coisa pode mudar a qualquer momento. A API pública não deve ser considerada estável. Depois de lançar 1.0.0, você se compromete a seguir as regras do SemVer para todos os lançamentos subsequentes.
Posso usar v como prefixo (v1.2.3)?
A especificação SemVer não inclui um prefixo v — o formato canônico é 1.2.3. No entanto, muitas ferramentas (tags do Git, releases do GitHub) usam convencionalmente v1.2.3. A maioria dos validadores aceita ambas as formas.
O que acontece se eu esquecer de incrementar a versão major para uma mudança incompatível?
Os consumidores que usam intervalos caret receberão automaticamente a atualização e seus builds podem quebrar inesperadamente. É por isso que a disciplina no SemVer é crítica — é um contrato social entre os autores de bibliotecas e os consumidores.