1. O Que E SemVer

Semantic Versioning (SemVer) e uma especificacao criada por Tom Preston-Werner que define como os numeros de versao de software devem ser atribuidos e incrementados. O objetivo e comunicar de forma clara o tipo de mudanca que ocorreu em cada versao, permitindo que usuarios e ferramentas automatizadas tomem decisoes informadas sobre atualizacoes.

SemVer e amplamente adotado pelo ecossistema JavaScript (npm), Rust (cargo), Go modules, e muitas outras plataformas. Entender SemVer e fundamental para qualquer desenvolvedor que publica ou consome bibliotecas.

2. Formato Completo

O formato completo de uma versao SemVer e:

MAJOR.MINOR.PATCH[-pre-release][+build-metadata]

Exemplos validos: 1.0.0, 2.1.3, 1.0.0-alpha.1, 1.0.0-beta+20230101, 0.1.0-rc.1+sha.abc123.

3. As Regras de Cada Componente

• MAJOR: incrementado quando ha mudancas incompativeis com a API publica. Quando MAJOR e incrementado, MINOR e PATCH voltam a 0.
• MINOR: incrementado quando nova funcionalidade compativel e adicionada. Quando MINOR e incrementado, PATCH volta a 0.
• PATCH: incrementado quando ha correcoes de bugs compativeis com versoes anteriores.
• Versao 0.y.z: indica desenvolvimento inicial — qualquer coisa pode mudar a qualquer momento; a API publica nao deve ser considerada estavel.

4. Pre-release e Build Metadata

Pre-release identifiers sao adicionados apos um hifen e consistem em identificadores alfanumericos separados por ponto. Uma versao pre-release tem precedencia menor que a versao normal associada:

Ordem de precedencia: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0

Build metadata, adicionada apos um +, deve ser ignorada na comparacao de versoes — duas versoes que diferem apenas no build metadata tem a mesma precedencia.

5. Relacao com Conventional Commits

Conventional Commits e Conventional Commits formam um par natural para automatizar o versionamento:

• Commits do tipo fix correspondem ao PATCH do SemVer
• Commits do tipo feat correspondem ao MINOR do SemVer
• Commits com BREAKING CHANGE correspondem ao MAJOR do SemVer

Ferramentas como semantic-release e standard-version leem o historico de commits para determinar automaticamente qual bump de versao aplicar no proximo release.

6. Perguntas Frequentes

Posso comecar com 0.1.0 em vez de 1.0.0?

Sim. A versao 0.x.y e especial no SemVer e indica desenvolvimento inicial. A API publica nao e considerada estavel e qualquer mudanca pode ser feita sem incrementar MAJOR. Quando o software estiver pronto para uso em producao, voce faz o bump para 1.0.0.

Posso ter numeros de versao como 1.0.0.1?

Nao. O SemVer estritamente define o formato como tres numeros inteiros separados por pontos. Numeros como 1.0.0.1 nao sao SemVer validos. Se voce precisa de identificacao adicional, use build metadata (1.0.0+build.1).

Como comparar versoes com pre-release?

Versoes pre-release tem precedencia menor que a versao normal equivalente. 1.0.0-alpha e menor que 1.0.0. Entre pre-releases, a comparacao e feita identificador por identificador: numericos sao comparados como inteiros; alfanumericos sao comparados lexicograficamente.