Versionamento

O stCall adota o Versionamento Semântico 2.0.0 (SemVer) como padrão oficial para controle de versões. Este documento descreve as regras, convenções e práticas de versionamento do projeto.

Formato

MAJOR.MINOR.PATCH

Exemplos válidos:

1.0.0
1.2.3
2.0.0-alpha
2.0.0-beta.1
2.0.0+build.20240101

Cada componente é um inteiro não-negativo sem zeros à esquerda:

• MAJOR — versão principal (quebra de compatibilidade)
• MINOR — versão secundária (nova funcionalidade compatível)
• PATCH — versão de correção (correção de bug compatível)

As 11 Regras do SemVer

Regra 1 — API Pública Declarada

O software que usa SemVer deve declarar uma API pública, documentada com precisão no próprio código ou em documentação externa.

Regra 2 — Formato e Incremento Numérico

A versão deve seguir o formato X.Y.Z, onde X, Y e Z são inteiros não-negativos sem zeros à esquerda. Cada elemento deve aumentar numericamente.

1.9.0 → 1.10.0 → 1.11.0   ✅ correto
1.09.0                      ❌ zero à esquerda

Regra 3 — Imutabilidade de Versão Publicada

Uma versão já lançada não pode ser modificada. Qualquer alteração deve ser publicada como uma nova versão.

Regra 4 — Desenvolvimento Inicial (0.y.z)

A versão 0.y.z é reservada para desenvolvimento inicial. Qualquer coisa pode mudar a qualquer momento. A API pública não é considerada estável.

Regra 5 — Versão 1.0.0 Define a API Pública

A versão 1.0.0 define a API pública estável. A partir daqui, as regras de incremento de versão passam a se aplicar integralmente.

Regra 6 — PATCH: Correções Compatíveis

O PATCH deve ser incrementado apenas para correções de bugs retrocompatíveis.

1.2.3 → 1.2.4   ✅ bug fix retrocompatível

Ao incrementar PATCH, os demais componentes permanecem iguais.

Regra 7 — MINOR: Funcionalidade Compatível

O MINOR deve ser incrementado quando:

• Nova funcionalidade retrocompatível é introduzida
• Uma funcionalidade existente é marcada como depreciada
• Melhorias substanciais são feitas internamente

O PATCH deve ser zerado ao incrementar MINOR.

1.2.4 → 1.3.0   ✅ nova feature retrocompatível

Regra 8 — MAJOR: Quebra de Compatibilidade

O MAJOR deve ser incrementado quando qualquer mudança incompatível com versões anteriores é introduzida na API pública. MINOR e PATCH devem ser zerados.

1.3.0 → 2.0.0   ✅ breaking change

O MAJOR também pode ser incrementado junto de mudanças MINOR e PATCH.

Regra 9 — Pré-Releases

Versões de pré-release são indicadas com um hífen após o PATCH, seguido de identificadores separados por ponto.

1.0.0-alpha
1.0.0-alpha.1
1.0.0-beta
1.0.0-beta.2
1.0.0-rc.1

Regras dos identificadores:

• Apenas alfanuméricos ASCII e hífens: [0-9A-Za-z-]
• Não podem ser vazios
• Identificadores numéricos não podem ter zeros à esquerda

Versões de pré-release têm precedência menor que a versão normal correspondente:

1.0.0-alpha < 1.0.0

Regra 10 — Metadados de Build

Metadados de build são indicados com + após o PATCH ou pré-release.

1.0.0+build.001
1.0.0-beta+exp.sha.5114f85

Metadados de build devem ser ignorados ao determinar precedência. Duas versões que diferem apenas nos metadados têm a mesma precedência.

Regra 11 — Precedência

Precedência é calculada separando a versão em: MAJOR, MINOR, PATCH, pré-release (nessa ordem).

1. MAJOR, MINOR e PATCH são comparados numericamente
2. Quando MAJOR, MINOR e PATCH são iguais, pré-release tem precedência menor que a versão normal
3. Pré-releases são comparados identificador por identificador da esquerda para direita:
   • Identificadores numéricos são comparados numericamente
   • Identificadores alfanuméricos são comparados em ordem ASCII
   • Identificadores numéricos têm menor precedência que alfanuméricos
   • Um conjunto maior de campos tem maior precedência se todos os anteriores forem iguais

Exemplo completo de precedência:

1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0

Convenções do stCall

Versão Atual

O stCall está atualmente em desenvolvimento inicial. A versão segue o padrão 0.y.z até que a primeira release estável seja declarada.

Onde a Versão é Definida

Os dois pacotes devem ser versionados em conjunto — ambos sempre devem ter a mesma versão.

Quando Incrementar Cada Componente

PATCH (ex: 0.5.2 → 0.5.3)

• Correção de bug no frontend ou backend
• Ajuste de layout sem mudança funcional
• Correção de erro de digitação em mensagens
• Melhoria de performance sem mudança de interface

MINOR (ex: 0.5.2 → 0.6.0)

• Nova funcionalidade adicionada ao painel administrativo
• Novo evento AMI tratado no stcall-ws
• Nova API endpoint adicionada
• Novo componente de UI com funcionalidade
• Depreciação de comportamento (sem remoção ainda)

MAJOR (ex: 0.5.2 → 1.0.0 ou 1.x.y → 2.0.0)

• Mudança no protocolo WebSocket que quebra clientes existentes
• Alteração incompatível em endpoints de API já utilizados em produção
• Reestruturação do esquema do banco que requer migração manual
• Remoção de funcionalidade depreciada

Tags de Pré-Release

Para releases intermediários use os sufixos:

Exemplo de ciclo de release:

1.0.0-alpha → 1.0.0-beta → 1.0.0-rc.1 → 1.0.0-rc.2 → 1.0.0

Tags Git

Ao criar um release, criar uma tag Git com o prefixo v:

git tag -a v1.2.3 -m "Release 1.2.3"
git push origin v1.2.3

Perguntas Frequentes

Por onde começar?

Inicie com 0.1.0 e incremente o MINOR a cada novo release durante o desenvolvimento inicial.

Quando lançar 1.0.0?

Quando o software estiver pronto para produção e a API estiver estável o suficiente para que outros dependam dela. No contexto do stCall, isso ocorre quando a plataforma for disponibilizada para uso comercial.

O que fazer com uma breaking change acidental em um MINOR?

Lançar imediatamente uma nova versão MINOR que restaure o comportamento anterior. Documentar a versão problemática. Considerar a versão defeituosa como "retirada":

1.2.0 (breaking acidental) → 1.2.1 (restaura comportamento) → 1.3.0 (breaking intencional, se necessário)

Como versionar dependências atualizadas?

• Atualização que não afeta a API pública → PATCH (se for correção) ou MINOR (se for nova funcionalidade interna)
• Atualização que altera comportamento visível → classificar conforme o impacto externo

Como depreciar uma funcionalidade?

1. Documentar a depreciação e emitir um release MINOR com aviso
2. Em um release MAJOR futuro, remover a funcionalidade

1.4.0 — marca endpoint /api/v1/foo como depreciado (aviso nos logs)
2.0.0 — remove endpoint /api/v1/foo

Gramática Formal (BNF)

<valid semver> ::= <version core>
                 | <version core> "-" <pre-release>
                 | <version core> "+" <build>
                 | <version core> "-" <pre-release> "+" <build>

<version core> ::= <major> "." <minor> "." <patch>

<major> ::= <numeric identifier>
<minor> ::= <numeric identifier>
<patch> ::= <numeric identifier>

<pre-release> ::= <dot-separated pre-release identifiers>
<build>       ::= <dot-separated build identifiers>

<dot-separated pre-release identifiers> ::= <pre-release identifier>
    | <pre-release identifier> "." <dot-separated pre-release identifiers>

<pre-release identifier> ::= <alphanumeric identifier> | <numeric identifier>
<build identifier>       ::= <alphanumeric identifier> | <digits>

<alphanumeric identifier> ::= <non-digit>
    | <non-digit> <identifier characters>
    | <identifier characters> <non-digit>
    | <identifier characters> <non-digit> <identifier characters>

<numeric identifier> ::= "0" | <positive digit> | <positive digit> <digits>

<identifier characters> ::= <identifier character>
    | <identifier character> <identifier characters>

<identifier character> ::= <digit> | <non-digit>
<non-digit>            ::= <letter> | "-"
<digits>               ::= <digit> | <digit> <digits>
<digit>                ::= "0" | <positive digit>
<positive digit>       ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
<letter>               ::= "A" | ... | "Z" | "a" | ... | "z"

Regex de Validação

Para validar uma string SemVer (ECMA Script / JavaScript):

/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/

Exemplo de uso:

const SEMVER_REGEX =
  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/

function isValidSemver(version: string): boolean {
  return SEMVER_REGEX.test(version)
}

isValidSemver('1.2.3')        // true
isValidSemver('1.2.3-beta.1') // true
isValidSemver('1.2')          // false
isValidSemver('v1.2.3')       // false — prefixo 'v' não faz parte do SemVer

Referência

• Especificação oficial: semver.org/spec/v2.0.0.html
• Autoria: Tom Preston-Werner
• Licença: Creative Commons CC BY 3.0