CalVer é uma convenção de versionamento baseada no lançamento do seu projeto conforme o calendário, em vez de números arbitrários.

O versionamento fica melhor com o tempo.

Para mantenedores, o versionamento nos permite especificar dependências precisas dentro de um ecossistema em constante expansão. Para vendedores e promotores, a versão do projeto é uma parte dinâmica de uma marca. Para todos nós, o versionamento nos permite fazer referência ao passado enquanto atualizamos para o futuro.

Projetos diferentes usam sistemas diferentes para controle de versão, mas práticas surgiram. Por exemplo, números separados por pontos (por exemplo, 3.1.4) são praticamente dados. Outro padrão de versionamento comum incorpora um elemento baseado no tempo, geralmente parte da data de lançamento.

Essa abordagem baseada em data passou a ser chamada de Versionamento de Calendário, ou CalVer para abreviar.

Esquema

Existem vários esquemas de versionamento de calendário, muito usados por projetos grandes e pequenos. Em vez de declarar um único esquema como CalVer, é importante reconhecer a praticidade de cada um e projetar o esquema (Inglês) para se adequar ao projeto. Primeiro, as partes da versão:

• Major - O primeiro número da versão. 2 e 3 são as famosas versões principais do Python. O segmento major é o componente baseado em calendário mais comum.
• Minor - O Segundo número da versão. 7 é a versão secundária mais popular do Python.
• Micro - O terceiro e geralmente último número da versão. Às vezes referido como o segmento "patch".
• Modifier - Uma tag de texto opcional, como "dev", "alpha", "beta", "rc1" e assim por diante.

A grande maioria dos identificadores de versão modernos são compostos por dois ou três segmentos numéricos, mais o modificador opcional. A convenção sugere que versões de quatro segmentos numéricos sejam desencorajadas.

Projetando uma versão (Inglês)

Como veremos nos Estudos de caso abaixo, projetos têm encontrado mais de uma maneira útil de aproveitar as datas em suas versões. Em vez de escolher um único esquema, o CalVer apresenta terminologia padrão para desenvolvedores, além de versões "semânticas":

• YYYY - Ano completo - 2006, 2016, 2106
• YY - Ano curto - 6, 16, 106
• 0Y - Ano preenchido com zeros - 06, 16, 106
• MM - Mês curto - 1, 2 ... 11, 12
• 0M - Mês preenchido com zeros - 01, 02 ... 11, 12
• WW - Semana curta (desde o início do ano) - 1, 2, 33, 52
• 0W - Semana preenchida com zeros - 01, 02, 33, 52
• DD - Dia curto - 1, 2 ... 30, 31
• 0D - Dia preenchido com zeros - 01, 02 ... 30, 31

Note que os números de versão incrementados tradicionalmente são baseados em 0, enquanto os segmentos de data são baseados em 1 e os anos curtos e preenchidos com zeros são relativos ao ano 2000. Observe também que o uso de semanas é geralmente mutuamente exclusiva com meses/dias.

O Calendário Gregoriano é assumido, assim como a convenção de UTC. Tecnicamente, qualquer calendário pode ser usado, desde que os projetos indique qual deles.

Estudos de caso

CalVer tem alguns usuários. Estes projetos foram selecionados por sua notabilidade e variadede de casos de uso.

Ubuntu

Ubuntu, um dos mais proeminentes sistemas operacionais baseados em Linux disponíveis, usa um esquema CalVer de três segmentos, com ano curto e mês preenchido com zeros. Tem feito isso desde o início, em Outubro de 2004, tornando 4.10 a primeira versão geral do Ubuntu.

Mesmo um sistema operacional simples envolve muitas, muitas partes, tornando difícil comunicar muito significado com um número arbitrário. Datando lançamentos do projeto, a versão baseada em calendário é muito mais do que um número arbitrário, comunicando informações úteis que são enraizadas em um dado simples.

O Ubuntu obtém benefícios adicionais de seu esquema CalVer, ao integra-lo com seu cronograma de suporte. O Ubuntu atualmente tem períodos de suporte de cinco anos para seus lançamentos de suporte de longo prazo (LTS), e apenas 9 meses para versões não LTS. Graças ao CalVer e matemática elementar, qualquer usuário pode facilmente determinar se sua a versão ainda é suportada. A versão atual do LTS no momento da escrita, 16.04, terá suporte até abril de 2021.

Twisted

Twisted, o venerado framework Python execução assíncrona de rede, usa um esquema CalVer de três segmentos, com um ano curto na versão major, mês curto na versão minor e micro/patch na terceira e última posição.

Lançado pela primeira vez em 2002 e ainda desenvolvido ativamente hoje, Twisted é uma biblioteca madura que cresceu para corresponder ao seu grande escopo. Ele apresenta tudo, desde um cliente IRC até um servidor HTTP e uma série de utilitários para programação concorrente. Como um sistema operacional, o Twisted tem muitas peças, tornando o SemVer um encaixe inadequado devido as partes individuais depreciando e quebrando a compatibilidade individualmente.

As partes não obsoletas do Twisted são compatíveis com versões anteriores entre cada versão sucessiva, e as alterações significativas são feitas com base no tempo, onde um ano e dois lançamentos devem se passar entre o lançamento da descontinuação da funcionalidade e remoção dela.

Seu esquema de versionamento se espalhou para projetos relacionados, incluíndo, Klein, Treq, e até mesmo uma das dependências do Twisted, PyOpenSSL.

youtube-dl

youtube-dl, o discreto aliado dos arquivistas de mídia em todos os lugares da Internet, uses a usa um esquema CalVer de três segmentos, incluindo o ano inteiro, mês preenchido com zeros, e dia preenchido com zeros. A versão é quase totalmente orientada por calendário, exceto por um micro segmento que é adicionado em alguns contextos técnicos.

Apesar do nome, o escopo do youtube-dl é expansivo. Ele suporta extrair áudio e vídeo de uma lista longa e cada vez maior de sites. Considere o rápido ciclo de lançamento de serviços suportados, e fica claro por que o projeto adotou o CalVer com tanto grau de sucesso.

pytz

pytz é a tradução Python do banco de dados de fuso horários do IANA/Olson, o banco de dados por trás da precisão de tempo para todo o mundo da informática. pytz usa um esquema CalVer de dois segmentos, incluindo ano completo e versão secundária.

Embora Python tenha um histórico de arquitetura "baterias inclusas", e o módulo datetime menciona frequentemente fusos horários, o runtime core do Python não inclui informações de fuso horário. Isto é porque as atualizações de fuso horário não seguem um cronograma fixo e estão sujeitas a política e capricho legislativo. O CalVer oferece um retrato com data-estampada de um sistema caótico.

Teradata

O Teradata UDA client prove acesso de próxima geração para tecnologias de armazenamento de dados para a Teradata

O uso do Teradata é notável não pelo destaque da tecnologia ou empresa, mas porque houve vários lançamentos em 2016 que foram versionados como 15.10. Isso pode parecer complicado no início, mas o significado e a utilidade são claros.

Os mantenedores da biblioteca criaram um híbrido engenhoso de versionamento semântico e CalVer. A parte da versão YY.MM é usada como uma versão major combinada do SemVer. Que é, para novos lançamentos, a API da biblioteca permanece a mesma deste que foi criada em outubro de 2015. O código dependente escrito desde então é seguro para atualizar. Veremos os segmentos do ano e do mês atualizados na próxima vez que houver uma alteração significativa na API.

Outros projetos notáveis

• Unity - YYYY.MINOR.MICRO - Engine de jogos multiplataforma.
• pip - YY.MINOR.MICRO - Gerenciador de pacotes oficial do Python.
• PyCharm - YYYY.MINOR.MICRO - A IDE líder do Python.
• OpenSCAD - YYYY.0M - O programa open-source para modelagem CAD 3D sólida.
• fusefs-ntfs - YYYY.MM.DD_MICRO - Uma das mais antigas e mais multiplataforma camadas de acesso NTFS para Unix systems.
• certifi - YYYY.MM.DD - certifi é o empacotador ao redor do pacote autoridade certificadora da Mozilla, usada para comunicação segura da Internet. Similar ao pytz, atualizações de certificados não seguem um cronograma fixo, mas temporal, atualizações datáveis são críticas para a segurança.
• boltons - YY.MINOR.MICRO - Uma ampla biblioteca de utilitários que complementam a biblioteca standard do Python.

Veja a Página de usuários para uma lista crescente de usuários CalVer.

Quando utilizar o CalVer

Se você e pessoas que você não conhece levam seu projeto a sério, então use uma versão séria. Felizmente, a decisão de usar o CalVer para essa versão é mais fácil do que nunca:

• Seu projeto apresenta um escopo grande ou em constante mudança??
  • Grandes sistemas e frameworks, como Ubuntu e Twisted.
  • Conjuntos de utilitários, como Boltons.
• O seu projeto é sensível-ao-tempo de alguma forma? Outras mudanças externas impulsionam novos lançamentos do projeto?
  • Requisitos de negócio, como o foco do Ubuntu em cronogramas de suporte.
  • Atualizações de segurança, como a necessidade de atualização dos certificados do certifi.
  • Mudanças políticas, como a manipulação de mudanças em fuso horário do pytz.

Se você respondeu sim a alguma dessas perguntas, a semântica do CalVer torna ele uma forte escolha para o seu projeto.