Você sabe organizar as versões do seu programa? Ou você cria os famosos “site novo”, “site antigo” e “site mais antigo que o antigo 2.0”? Esse post é para você que quer aprender a acabar com esse problema de vez.
Todos nós sabemos que quanto mais um sistema cresce e mais pacotes são adicionados a ele, maior será a possibilidade de você se deparar com um problema de versionamento.
Em sistemas que possuem muitas dependências, pode-se tornar um pesadelo lançar novos pacotes de versão. Caso as especificações das dependências são muito complexas você poderá ter um bloqueio de versão, que acontece quando não conseguimos atualizar um pacote sem ter que liberar novas versões de cada pacote dependente.
Como sugestão para solucionar esse problema, temos um conjunto de regrinhas:
Essas regras tem como base as práticas comuns de softwares fechados e open-source e, para que funcione, você precisa declarar uma API pública, podendo consistir de documentação ou ser determinada pelo próprio código. O importante é que esta API seja clara e precisa. Com a API pública identificada, você informa as mudanças com incrementos específicos para o seu número de versão.
Considere o seguinte formato de versão:
X.Y.Z (Maior.Menor.Correção)
As correções de falhas (bug fixes) que não afetam a API, incrementam a versão de Correção.
Adições e alterações compatíveis com as versões anteriores da API incrementam a versão Menor.
Alterações incompatíveis com as versões anteriores da API incrementam a versão Maior.
De acordo com o site semver.org, este sistema de versionamento é chamado de “Versionamento Semântico” e, de acordo com ele, os números de versão e a forma como eles mudam transmitem o significado do código subjacente e o que foi modificado de uma versão para a próxima.
Agora algumas regrinhas simples, mas importantes:
- Declarar uma API pública. Esta pode ser declarada no próprio código ou existir estritamente na documentação, sendo precisa e compreensiva.
- Seguir o formato X.Y.Z, onde X, Y e Z são inteiros não negativos e não devem conter zeros à esquerda. X é a versão maior, Y é a versão menor e Z é a versão de correção. Cada elemento deve aumentar numericamente. Exemplo 1.9.0 -> 1.10.0 -> 1.11.0.
- Qualquer modificação deve ser laçada como uma nova versão. Uma vez que um pacote versionado foi lançado, o conteúdo desta versão não deve ser modificado.
- No início do desenvolvimento, a versão Maior deve ser zero (0.y.z). Qualquer coisa pode mudar a qualquer momento. A API pública não deve ser considerada estável.
- Versão 1.0.0 define a API como pública. A maneira como o número de versão é incrementado após o lançamento é dependente da API pública e como ela muda.
- Versão de Correção Z (x.y.Z | x > 0) deve ser incrementado apenas se mantiver a compatibilidade e introduzir correção de bugs. Uma correção de bugs é definida como uma mudança interna que corrige um comportamento incorreto.
- Versão Menor Y (x.Y.z | x > 0) deve ser incrementada se for adicionada uma funcionalidade nova que seja compatível na API pública. Deve ser incrementada caso um funcionalidade da API pública for definida como descontinuada e, também, pode ser incrementada se uma nova funcionalidade ou melhoria substancial for introduzida dentro do código privado. Pode incluir mudanças a nível de correção. A versão de Correção deve ser redefinida para 0 (zero) quando a versão Menor foi incrementada.
- Versão Maior X (X.y.z | X > 0) deve ser incrementada caso introduzidas mudanças incompatíveis na API pública. Pode incluir alterações a nível de versão Menor e de versão de Correção. Versão de Correção e Versão Menor deverão ser redefinidas para 0 (zero) quando a versão Maior for incrementada.
- Uma versão de pré-lançamento pode ser identificada adicionando um hífen e uma série de identificadores separados por ponto após a versão de correção. O identificador deverá incluir apenas caracteres alfanuméricos e hífen, não deve ser vazio e não deve incluir zeros à esquerda. Essas versões de pré-lançamento tem precedência inferior à versão normal a que está vinculada, portanto indica que a versão é instável e pode não satisfazer os requisitos de compatibilidade, como indicado por sua versão normal associada. Exemplo: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.
- Metadados de construção podem ser identificados adicionando um sinal de adição (+) e uma série de identificadores separados por ponto imediatamente após a Correção ou Pré-Lançamento. O identificador deverá ser composto apenas por caracteres alfanuméricos e hífen, não deve ser vazio e podem ser ignorados quando se determina a versão de precedência. Neste caso, duas versões que se diferem apenas nos metadados de construção, têm a mesma precedência. Exempo: 1.0.0-alpha+001, 1.0.0+2030313144700, 1.0.0-beta+exp.sha.5114f85
- A precedência deve ser calculada separando identificadores de versão Maior, Menor, Correção e Pré-lançamento, nesta ordem. Precedência refere como as versões são comparadas com cada outra quando solicitado. Metadados de construção não figuram na precedência. É determinada pela primeira diferença ao comparar cada identificador da esquerda para a direita. Exemplo: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. Quando Maior, Menor e Correção são iguais, a versão de Pré-Lançamento tem precedência menor que a versão normal. Exemplo: 1.0.0-alpha < 1.0.0. A precedência entre duas versões de Pré-Lançamento com mesma versão Maior, Menor e Correção deve ser determinada comparando cada identificador separado por ponto da esquerda para direita até que seja encontrada diferença da seguinte forma: identificadores com apenas dígitos são comparados numericamente e identificadores com letras ou hífen são comparados lexicalmente na ordem de classificação ASCII. Identificadores numéricos sempre têm menor precedência do que os não numéricos. Um conjunto maior de campos de pré-lançamento tem uma precedência maior do que um conjunto menor, se todos os identificadores anteriores são iguais. Exemplo: 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.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.
Caso queira saber mais, acesse o site abaixo: