Philip Withnall
philip.withnall@collabora.co.uk 2015
Versionamento e lançamento de bibliotecas e aplicativos
Rafael Fontenelle
rafaelff@gnome.org 2017

# Versionamento

#

        Resumo

        O versionamento é diferente para módulos de bibliotecas e aplicativos: as bibliotecas precisam de uma versão de libtool especificada junto com a versão de seu pacote. Por sua vez, aplicativos só possuem uma versão de pacote.

          Bibliotecas e aplicativos possuem uma versão de pacote na forma de maior.menor.micro. ()
          Adicionalmente, bibliotecas possuem uma versão de libtool na forma de atual:revisão:idade. ()
          Os números de versão devem ser atualizados a cada lançamento (usando incrementos de lançamento e pós-lançamento). ()
          As versões de pacotes devem ser incrementados por alterações ou adições de recursos. ()
          As versões de libtool devem ser atualizadas por alterações ou adições de API. ()
          Versões menores pares/ímpares de pacotes podem ser usadas respectivamente para lançamentos estáveis/instáveis. ()

# Versionamento de pacote

Bibliotecas e aplicativos possuem uma versão de pacote na forma de maior.menor.micro.

O número de versão de pacote é aquele passado para `AC_INIT()` e que geralmente é conhecido como número de versão do projeto. Por exemplo, o pacote Debian para uma biblioteca vai usar a versão de pacote da biblioteca (apesar de também poder incluir o número de versão maior no nome de pacote para permitir instalabilidade paralela). Versões de pacotes são atualizadas pelas seguintes regras:

Se for quebrar a compatibilidade de API em uma biblioteca, ou fazer uma alterações a um aplicativo que afeta tudo (tal como um redesenho da interface gráfica), incremente a versão maior e defina a menor e micro para 0.

Do contrário, se for alterar ou adicionar um recurso, ou adicionar qualquer API, incremente a versão menor e defina micro para 0.

Do contrário (se for fazer um lançamento contendo apenas correções de erros e atualizações de tradução), incremente a versão micro.

Note que o número da versão menor deve ser atualizada se qualquer API for adicionada.

# Versionamento de libtool

Bibliotecas possuem dois números de versão: uma versão de libtool que rastreia a compatibilidade reversa com ABI (veja ) e uma versão de pacote que rastreia alterações de recursos. Esses são normalmente incrementados em sincronização, mas devem ser mantidos separados por causa de compatibilidade reversa com ABI não está necessariamente relacionada a alterações de recursos ou correções de erros. Além do mais, os dois números de versões possuem semânticas diferentes e não podem ser gerados automaticamente para cada um.

Uma boa visão geral do versionamento de libtool, e as diferenças para versionamento de pacote, é fornecida no Autotools MythBuster; outro está no manual do libtool.

Para atualizar a versão do libtool, siga o algoritmo fornecido nos comentários abaixo. Esse é tipicamente um bloco de código do configure.ac para configurar versionamento de libtool:

# Before making a release, the LT_VERSION string should be modified. The # string is of the form c:r:a. Follow these instructions sequentially: # 1. If the library source code has changed at all since the last update, then # increment revision (‘c:r:a’ becomes ‘c:r+1:a’). # 2. If any interfaces have been added, removed, or changed since the last # update, increment current, and set revision to 0. # 3. If any interfaces have been added since the last public release, then # increment age. # 4. If any interfaces have been removed or changed since the last public # release, then set age to 0. AC_SUBST([LT_VERSION],[0:0:0])

O bloco de código a seguir pode ser usado em um Makefile.am para passar aquela informação de versão para o libtool:

minha_biblioteca_la_LDFLAGS = -version-info $(LT_VERSION)

# Versões estáveis e instáveis de pacote

A maioria dos módulos do GNOME seguem uma convenção para lançamentos estáveis e instáveis. A versão menor é par para lançamentos estáveis e é ímpar para lançamentos instáveis. Por exemplo, as versões 3.20.* são estáveis, mas as versões 3.19.* são instáveis. As versões 3.19.* podem ser vistas como lançamentos alfa e beta da versão 3.20.

Uma nova versão micro estável (ex.: 3.20.0 → 3.20.1) não adiciona novos recursos, apenas atualizações de tradução e correções de erro. Por outro lado, lançamentos micro instáveis (ex.: 3.19.1 → 3.19.2) podem adicionar API, ou alterar ou remover API que foi adicionada em um lançamento micro anterior naquela séries menores.

A versão libtool deve ser atualizada apenas para versões de pacote estável.

# Processo de lançamento

O processo padrão para fazer um lançamento de um módulo incrementa a versão de libtool (se o módulo é uma biblioteca) em tempo de lançamento e, imediatamente após, incrementa o número de versão do pacote (isso é chamado de “incremento pós-lançamento” ou, em inglês, “post-release increment”)

Atualizar as versões de libtool em tempo de lançamento significa que eles são incrementados apenas uma vez para todas as alterações de ABI em um lançamento. O uso de incremento pós-lançamento para versões de pacotes significa que o número de versão de pacote não está desatualizado (ainda igual ao lançamento anterior) durante o ciclo de desenvolvimento.

O processo de lançamento (baseado no processo de lançamento do GNOME):

Certifique-se de que o código esteja atualizado: git pull

Certifique-se de que você tenha nenhuma alteração local: git status

Se o lançamento é para uma versão de pacote estável, incremente o número de versão de libtool no configure.ac (se ele existir)

Adicione uma entrada ao arquivo NEWS

Execute ./autogen.sh && make && make install && make distcheck e certifique-se de que foi concluído com sucesso

Corrija quaisquer problemas que aparecerem, faça o commit das alterações e reinicie no passo 3

Se make distcheck finalizar com “[archive] is ready for distribution”, execute git commit -a -m "Release version x.y.z" (sendo “x.y.z” o número da versão do pacote)

Execute git push

Se isso falhar em razão de outros commits terem sido enviados (push) neste meio tempo, execute git pull para mesclar seu commit no ramo seguido por um segundo git push. Isso é uma exceção às diretrizes do GNOME de ter um histórico de git linear (). Se você prefere ter um histórico linear, você precisa reiniciar o passo 1.

Crie uma tag de lançamento: git tag -s x.y.z (sendo “x.y.z” o número de versão do pacote)

Execute git push origin x.y.z (sendo “x.y.z” o número de versão do pacote)

O lançamento agora está completo e o incremento de versão pós-lançamento pode ser feita:

Incremente o número de versão de pacote no configure.ac

Execute git commit -a -m "Post-release version increment"

Execute git push

O arquivo de pacote gerado por make distcheck agora pode ser enviado para download.gnome.org ou distribuído em outras formas.