Qual numero de versao voce coloca quando corrige um bug? E quando adiciona um recurso que quebra tudo? Essa duvida divide equipes de desenvolvimento. De um lado, o versionamento semantico padroniza cada numero. Do outro, o convencional deixa tudo mais solto. Nao existe certo absoluto, existe o padrao certo para o seu contexto.
Versionamento semantico (SemVer) usa MAJOR.MINOR.PATCH. A versao 2.1.3 indica: MAJOR 2 (quebra de compatibilidade), MINOR 1 (nova funcionalidade retrocompativel), PATCH 3 (correcao de bug). O convencional nao segue essa matematica. Ele pode usar 1.0, depois 2.0, depois 2.5, sem compromisso com significado.
Clareza para usuarios
O SemVer transmite intencao. Quando uma API publica sai da 1.0 para a 2.0, o consumidor sabe que precisa revisar integracoes. Isso reduz surpresa e acidentes em producao. O convencional, por outro lado, nao comunica nada alem de "mudou". Para bibliotecas publicas e APIs, essa falta de sinal vira custo.
No entanto, para um projeto interno que ninguem consome, o SemVer pode ser burocracia pura. Voce gasta tempo decidindo se aquela alteracao e MAJOR ou MINOR quando o resultado pratico e o mesmo. O convencional acelera o ritmo.
Previsibilidade e automacao
SemVer permite ferramentas de release automatizado. O conventional commits (padrao de mensagens) gera changelog e decide o proximo numero com base no tipo de commit. Isso elimina debate humano. O convencional exige decisao manual a cada release, o que abre espaco para erros e inconsistencias.
Mas o SemVer so funciona se a disciplina existir. Um commit errado que classifica breaking change como feat corrompe toda a sequencia. A promessa de automacao falha quando o time nao segue o padrao.
Curva de aprendizado
SemVer tem regras claras e documentacao oficial. Aprender leva minutos. O convencional parece simples porque nao tem regra, mas essa liberdade gera conflitos: cada dev tem uma logica propria para escolher o numero. O resultado e um historico que ninguem consegue interpretar.
| Criterio | Semantico (SemVer) | Convencional | |---|---|---| | Formato | MAJOR.MINOR.PATCH | Livre (1.0, 2.3, 5) | | Significado | Cada numero tem funcao | Sem compromisso | | Automacao | Facil com conventional commits | Manual | | Publico ideal | APIs, bibliotecas, produtos publicos | Projetos internos, prototipos | | Risco principal | Exige disciplina do time | Historico sem padrao |
Veredito
Para quem mantem API publica ou biblioteca usada por terceiros, escolha o versionamento semantico. Ele protege seus consumidores de quebras silenciosas. Para quem trabalha com aplicacao interna ou prototipo que muda rapido, o convencional resolve com menos atrito. A pergunta certa nao e qual e o melhor padrao, e quem depende da sua versao. Se a resposta for "ninguem", nao complique. Se for "clientes", SemVer nao e opcional.
FAQ
Versionamento semantico e convencional podem ser usados juntos?
Sim. Muitas equipes usam SemVer para o numero da versao e conventional commits para padronizar mensagens. Nesse caso, o convencional se refere ao estilo de commit, nao ao numero. A combinacao e comum em projetos open source.
Qual a diferenca entre versionamento semantico e conventional commits?
Versionamento semantico define o formato do numero (MAJOR.MINOR.PATCH). Conventional commits define como escrever mensagens de commit (feat, fix, breaking). O SemVer pode funcionar sem conventional commits, mas as ferramentas de automacao costumam integrar os dois.
Quando devo incrementar o numero MAJOR no SemVer?
Quando voce faz mudanca que quebra compatibilidade com versoes anteriores. Isso inclui remover um endpoint, mudar um parametro obrigatorio ou alterar o formato de resposta. Um MAJOR novo exige comunicacao clara no changelog.
O versionamento convencional e adequado para bibliotecas publicas?
Nao e recomendado. Bibliotecas publicas precisam de previsibilidade. O convencional nao informa se uma atualizacao e segura ou se vai quebrar o codigo do consumidor. SemVer se tornou padrao em ecossistemas como npm e PyPI por esse motivo.
Como escolher entre os dois para um projeto novo?
Avalie o publico. Se o projeto sera consumido por outras equipes ou clientes externos, comece com SemVer desde a versao 0.1.0. Se for interno e descartavel, use convencional ate estabilizar e migre depois, se necessario.