TerraLib and TerraView Wiki Page

This is an old revision of the document!


TerraLib and TerraView Versioning

Esta seção apresenta a política de versionamento adotada da TerraLib, compreendendo todo o ciclo de vida da plataforma, 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.

Numeração das Versões

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 (ou revision number).

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 desenvolvedores, clientes da API TerraMA2, 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 numeração z, chamada patch version ou revision number, é usada para identificar as versões estáveis de uma geração y. Estas versões z não incluem modificações e novas funcionalidades na API, elas apenas garantem que as funcionalidades foram testadas e encontram-se em um estado confiável. Novas numerações serã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 no TerraMA2 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) não passarão 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:

TODO

Versionamento Repositório

O versionamento do repositório considera que:

  • O ramo develop sempre estará livre para evolução da tecnologia.
  • Para cada versão menor do cronograma será criado um ramo com o seu nome. Exemplos: release-5.0, release-5.1.
  • Nos ramos das versões menores, como o release-5.0, trabalharemos apenas na correção de erros e estabilização de código, devendo as correções serem aplicadas a todos os ramos relacionados. Este ramo será congelado, isto é, não iremos incluir novas funcionalidades, apenas vamos gerar correções dessa versão.
  • Para cada versão lançada, iremos criar uma tag com a seguinte nomenclatura: v-x.y.z. Assim teremos as tags: v-5.0.0, v-5.0.1, v-5.1.0, v5.1.1.

A figura abaixo ilustra o esquema de versionamento adotado.

TODO

API em Desuso

Classes, métodos 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.

Macros e Classes de Versionamento

As macros, definidas no projeto de build da TerraLib (CMakeLists.txt principal), para controle do versionamento são:

  • TERRALIB_VERSION_MAJOR : número da versão da TerraLib;
  • TERRALIB_VERSION_MINOR: número da revisão menor da TerraLib;
  • TERRALIB_VERSION_PATCH: número da correção;
  • TERRALIB_VERSION_STATUS: tipo de distribuição (alpha, beta, release candidate);
  • TERRALIB_VERSION_STRING: versão em um formato string;
  • TERRALIB_VERSION: versão no formato inteiro, com o intuito de possibilitar que as aplicações escrevam códigos dependentes de versão da TerraLib.

As variáveis acima podem ser encontradas no arquivo build/cmake/CMakeLists.txt.

Além das variáveis acima, existe a classe terralib::common::Version que permite obter as informações acima em tempo de execução das aplicações, assim como a data de build da distribuição da TerraLib.

Procedimento de Versionamento

TODO: pegar do arquivo README

Veja Também os Seguintes Documentos