====== Versionamento Semântico ======

Para padronizar as versões de nossos softwares, adotamos o padrão [[https://semver.org|Semantic Versioning 2.0.0]].

Este artigo descreve o padrão de versionamento semântico.

===== Objetivos =====

  * Identificar nossos softwares através da versão.
  * Trazer clareza e previsibilidade sobre a mudança de versão.
  * Saber o que muda de uma versão para a outra. (Se é um bug, um feature)
  * Saber se a API de uma versão é compatível com a anterior.
  * Permitir automatizar o versionamento durante o CI. Veja: [[pres:gerti:devops:informacoes:nomenclatura_commits|Nomenclatura dos Commits]]

===== Como funciona? =====

Esse padrão adiciona versões no formato: ''%%1.2.3%%'', ''%%1.3.0%%'', ''%%2.0.0%%''.

Ele permite saber:

  - Se uma versão é retro-compatível com outra.
  - O que muda de uma versão para outra. (Se é correção de bug ou se é feature)

==== Formato da versão ====

As versões de nossos softwares terão o seguinte formato:

<code>
<Major>.<Minor>.<Patch>
</code>

Por exemplo: ''%%1.3.4%%'', ''%%1.11.0%%'', ''%%3.0.1%%''.

==== Patch ====

O ''%%Patch%%'' significa **correções de bugs**. Sempre que houver uma correção de bug, o ''%%Patch%%'' aumenta em 1.

Exemplos:

  * ''%%1.3.0%%'' -> ''%%1.3.1%%''
  * ''%%2.15.23%%'' -> ''%%2.15.24%%''

==== Minor ====

O ''%%Minor%%'', número do meio, significa **implementação de feature**. Sempre que houver uma implementação de feature, o ''%%Minor%%'' aumenta em 1, e o ''%%Patch%%'' **reseta** para 0.

Exemplos:

  * ''%%1.0.4%%'' -> ''%%1.1.0%%''
  * ''%%3.4.1%%'' -> ''%%3.5.0%%''
  * ''%%1.9.0%%'' -> ''%%1.10.0%%''

==== Major ====

O ''%%Major%%'', 1⁰ número, indica que houve uma **BREAKING CHANGE** (mudança que quebra a compatibilidade com as versões anteriores). Sempre que houver uma **Breaking Change** o ''%%Major%%'' aumenta em 1, e o ''%%Minor%%'' e o ''%%Patch%%'' **resetam** para 0.

Exemplos:

  * ''%%1.3.4%%'' -> ''%%2.0.0%%''
  * ''%%4.13.72%%'' -> ''%%5.0.0%%''

=== Breaking Change ===

Breaking changes são mudanças que quebram a retrocompatibilidade com as versões anteriores.

Isso significa que, se houver outros programas que consumam da API desse programa, atualizar para a nova versão pode quebrar o programa que chama a API.

Isso pode acontecer por exemplo pois o nome do endpoint que era ''%%/get_nome/<id>%%'' virou ''%%/nome/<id>%%''. Quebrando a retrocompatibilidade.

===== Retrocompatibilidade =====

Sobre a retrocompatibilidade, versões que possuem a **mesma Major** são **compatíveis**, e versões que possuem **Major diferentes** **não** são **compatíveis**.

==== Na prática ====

  - É tranquilo atualizar da versão ''%%7.3.0%%'', para a ''%%7.4.0%%''.
  - Já atualizar da ''%%7.4.0%%'' para a ''%%8.0.0%%'' pode quebrar algum código, e requer uma análise. Vale a pena então olhar o Changelog para entender quais foram as mudanças entre cada versão.

===== Automação no CI/CD =====

Não será necessário aplicar as tags manualmente. A Pipeline de CI/CD possui um [[https://gitsource.tce.go.gov.br/GER-TI/tce.kubernetes/tce.templates/-/tree/main/templates/versioning|Job de Versionamento]] que aplica o versionamento **automaticamente**, com base no nome do commit, veja: [[pres:gerti:devops:informacoes:nomenclatura_commits|Nomenclaturas Commits]]