Versionamento

Esta seção apresenta a política de versionamento adotada na TerraLib.

O versionamento compreende todo o ciclo de vida da Plataforma TerraLib, incluindo:

• modificações e melhorias na API;
• lançamento de versões experimentais e de distribuição;
• criação de ramos e geração de tags no repositório de código.

As versões estáveis são numeradas usando-se a tripla x.y.z, que indica, respectivamente, os números conhecidos por Major Version, Minor Version e Patch Version.

A numeração x é usada para separar versões bem diferentes e que, geralmente, indicam uma grande mudança na API. Mudanças neste nível podem implicar desde a adição de um grande número de funcionalidades até saltos tecnológicos que culminem no rompimento total da API. Em resumo, os usuários podem esperar mudanças significativas da API.

A numeração y é usada para separar versões que adicionam novas funcionalidades, mas que não trazem grandes impactos nas aplicações existentes. Mudanças neste nível não devem acarretar incompatibilidades entre as APIs. Obviamente, o uso de recursos da nova versão farão com que o cliente não possa fazer a atualização para baixo novamente sem um mínimo de esforço de programação.

A numeracao z, chamada patch version ou revision number, é usada para identificar as versões estáveis de uma geracão y. Estas versões z não incluem modificações e novas funcionalidades, elas apenas garantem que as funcionalidades foram testadas e encontram-se em um estado confiável. Novas numerações são geradas à medida que uma determinada quantidade de erros seja descoberta e corrigida. É garantido que nenhuma mudança na API será realizada.

As versões de pré-lançamento (instáveis ou experimentais) possuem um qualificador extra, um sufixo da forma: -tipo-pré-lançamento.w. Até que uma versão atinja um ponto estável, passando por todos os testes de aceitação, esta versão passará, na ordem, pelos seguintes estados:

• alpha.w: a qualificação alpha é reservada para geração de versões preliminares que possam ser usadas por colaboradores e usuários que tenham produtos baseados na TerraLib e que tenham a necessidade de acompanhar os lançamentos mais recentes.
• beta.w: a qualificação beta indica que é um produto que já pode ser testado pelos colaboradores e usuários.
• rc.w: a qualificação release candidate indica que o produto já se encontra em um nível próximo de ser aceito, mas que ainda pode sofrer modificações devido a correções.

Exemplos de numerações de versões são:

• 5.1.0 = resultado das versões 5.1.0-alpha.1, 5.1.0-alpha.2, 5.1.0-beta.1, 5.1.0-rc.1, … , 5.1.0-rc.8.

As versões com numeração de correção (ex: 5.1.1) podem ou não passar por versões de pré-lançamento, uma vez que são apenas correções.

A figura abaixo ilustra o processo de numeração das versões:

O versionamento do repositório considera que:

1. novas versões da TerraLib, como 6 ou superior, serão hospedadas no mesmo repositório;
2. não existirão versões de correção até o lançamento da primeira versão estável 5.0.0;
3. o ramo principal só pode conter versões em ordem crescente, não podendo acomodar novas versões intermediárias, geradas posteriormente a um dado lançamento;
4. o ramo principal sempre estará livre para evolução da tecnologia.

Até o lançamento da versão estável 5.0.0, iremos criar um novo ramo derivado do principal toda vez que atingirmos uma data limite da versão de pré-lançamento (ex: B_05_00_00_alpha_1). Trabalharemos neste ramo para corrigir erros e estabilizarmos o código. As correções também serão aplicadas no ramo principal. Na data de lançamento da pré-versão, iremos subir uma tag no ramo criado (T_05_00_00_alpha_1). Neste ponto, este ramo será congelado, pois não vamos gerar correções dessas versões.

Quando atingirmos o ponto da primeira versão estável da geração 5, será criado um ramo chamado B_05 e outro derivado dele chamado B_05_00. Neste ponto todo o desenvolvimento de novas funcionalidades será realizado no ramo B_05, enquanto o ramo B_05_00 conterá apenas correções que serão aplicadas no ramo principal da geração 5 (B_05) e demais ramos de versões menores. Toda vez que o ramo com a versão menor atingir um ponto de estabilidade iremos criar tags. Estes ramos poderão ser mantidos para geração de quantas revisões desejarmos para a versão menor.

A figura abaixo ilustra este esquema.

<color red> TO BE DONE: </color>

Classes, método ou funções marcados com a macro TE_DEPRECATED devem ter seu uso evitados pois podem ser removidos entre as versões menores e maiores.

As macros disponíveis são:

• TERRALIB_MAJOR_VERSION: número da versão da TerraLib;
• TERRALIB_MINOR_VERSION: número da revisão menor da TerraLib;
• TERRALIB_PATCH_VERSION: número da correção;
• TERRALIB_RELEASE_STATUS: tipo de distribuição (alpha, beta, release candidate, stable);
• TERRALIB_STRING_VERSION: versão em um formato string;
• TERRALIB_INT_VERSION: versão no formato inteiro, com o intuito de possibilitar que as aplicações escrevam códigos dependentes de versão da TerraLib.

A classe te::common::Version permite obter as informações acima em tempo de execução e também a data de build da TerraLib.

<color red> TO BE DONE </color>

Editar as variáveis de versionamento no arquivo TerraLib.cmake contido na pasta build/terralib. As seguintes linhas devem ser editadas:

<color red> TO BE DONE</color>

Estas variáveis serão usadas juntamente com o arquivo de template TerraLibConfig.h.in (contido em src/terralib) para gerar o arquivo de inclusão TerraLibConfig.h. Este último arquivo conterá as macros com informação de versão que poderão ser usadas pelas aplicações.

Precisamos discutir alguns pontos como:

• Número de versões por ano: o ideal seria termos três versões menores por ano (uma a cada quatro meses). O número de revisões estáveis dependerá da quantidade de erros encontrados. No melhor caso teremos três versões estáveis.
• Período de estabilização do código: criação do ramo para a versão menor com pelo menos 35 dias antes da data limite da primeira versão estável, de forma que as correções de erros da fase de teste final possam ser aplicadas e reavaliadas. Tudo isso dependerá de que o módulo de testes unitários e sistema de build estejam 100%.
• Aplicação de correções: checklist para garantir que todas as correções sejam aplicadas nos ramos corretos.

Wikipedia:

• Software Versioning
• Deprecation