CalVer

Calendar Versioning

2019-07-01T07:00:00Z

CalVer is a versioning convention based on your project's release calendar, instead of arbitrary numbers.

Versioning gets better with time.

For maintainers, versioning allows us to specify precise dependencies within an ever-expanding ecosystem. For sellers and promoters, a project's version is a dynamic part of a brand. For all of us, versioning lets us reference the past while upgrading to the future.

Different projects use different systems for versioning, but common practices have emerged. For instance, point-separated numbers (e.g., 3.1.4) are all but given. Another common versioning pattern incorporates a time-based element, usually part of the release date.

This date-based approach has come to be called Calendar Versioning, or CalVer for short.

Contents

Scheme
Case studies
When to use CalVer

Scheme

There are multiple calendar versioning schemes, long used by projects big and small. Rather than declaring a single scheme to be CalVer, it's important to recognize the practicality of each and design the scheme to fit the project. First, the parts of the version:

Major - The first number in the version. 2 and 3 are Python's famous major versions. The major segment is the most common calendar-based component.
Minor - The second number in the version. 7 is the most popular minor version of Python.
Micro - The third and usually final number in the version. Sometimes referred to as the "patch" segment.
Modifier - An optional text tag, such as "dev", "alpha", "beta", "rc1", and so on.

The vast majority of modern version identifiers are composed of two or three numeric segments, plus the optional modifier. Convention suggests that four-numeric-segment versions are discouraged.

As seen in the case studies below, projects have found more than one useful way to leverage dates in their versions. Rather than choose a single scheme, CalVer introduces standard terminology for developers, in addition to the "semantic" versions:

YYYY - Full year - 2006, 2016, 2106
YY - Short year - 6, 16, 106
0Y - Zero-padded year - 06, 16, 106
MM - Short month - 1, 2 ... 11, 12
0M - Zero-padded month - 01, 02 ... 11, 12
WW - Short week (since start of year) - 1, 2, 33, 52
0W - Zero-padded week - 01, 02, 33, 52
DD - Short day - 1, 2 ... 30, 31
0D - Zero-padded day - 01, 02 ... 30, 31

Note that traditional, incremented version numbers are 0-based, whereas date segments are 1-based, and the short and zero-padded years are relative to the year 2000. Also note that usage of weeks is usually mutually exclusive with months/days.

The Gregorian calendar is assumed, as is the convention of UTC. Technically any calendar can be used, provided projects state which one.

Case studies

CalVer has quite a few users. These are projects selected for their notability and variety of use cases.

Ubuntu

Ubuntu, one of the most prominent Linux-based operating systems available, uses a three-segment CalVer scheme, with a short year and zero-padded month. It has done so from the very start, in October 2004, making 4.10 the first general release of Ubuntu.

Even a simple operating system involves many, many parts, making it difficult to communicate much meaning with an arbitrary number. By dating the project release, the calendar-based version is much more than an arbitrary number, communicating useful information that is rooted in simple fact.

Ubuntu derives additional benefit from its CalVer scheme, by integrating it with their support schedule. Ubuntu currently has five-year support periods for their long-term support (LTS) releases, and only 9 months for non-LTS releases. Thanks to CalVer and elementary arithmetic, any user can easily determine whether their version is still supported. The current LTS release at the time of writing, 16.04, will be supported until April 2021.

Twisted

Twisted, the venerated Python networking and asynchronous execution framework, uses a three-segment CalVer scheme, with a short year in the major version slot, short month in the minor version slot, and micro/patch version in the third and final slot.

First released in 2002 and still actively developed today, Twisted is a mature library that has grown to match its large scope. It features everything from an IRC client to an HTTP server to a slew of utilities for concurrent programming. Like an operating system, Twisted has a lot of parts, making SemVer a poor fit due to the individual parts deprecating and breaking compatibility individually.

The non-deprecated parts of Twisted are backwards-compatible between each successive version, and breaking changes are done on a time basis, where one year must pass and two releases issued between the release deprecating the functionality and the removal of the functionality.

Its versioning scheme has spread to related projects, including Klein, Treq, and even one of Twisted's dependencies, PyOpenSSL.

youtube-dl

youtube-dl, the understated ally of Internet media archivists everywhere, uses a three-segment CalVer scheme, including full year, zero-padded month, and zero-padded day. The version is almost completely calendar-driven, except for a micro segment that is added in some technical contexts.

Despite the name, youtube-dl's scope is expansive. It supports extracting audio and video from a long, ever-expanding list of sites. Consider the rapid release cycle of supported services, and it becomes clear why the project has adopted CalVer to such a great degree.

The IANA/Olson timezone database

The IANA/Olson timezone database represents the history of local time for many representative locations around the globe, and is the source of truth for essentially every operating system, database, website, or other computer that deals with timezones or daylight savings time.

It is updated periodically to reflect changes made by political bodies to time zone boundaries, UTC offsets, and daylight-saving rules. Because these changes follow politicical and legislative whim rather than a fixed schedule, the database is versioned with a four-digit year followed by lower-case letter (a through z, then za through zz, then zza through zzz, and so on). Calendar versioning offers a date-stamped snapshot of an otherwise chaotic system.

Teradata

The Teradata UDA client provides next-generation access to Teradata's data warehousing technologies.

Teradata's usage is notable not for the prominence of the technology or company, but because there have been multiple releases in 2016 which were versioned as 15.10. This may seem breaking at first, but the meaning and utility is clear.

The library maintainers have crafted a resourceful hybrid of semantic versioning and calendar versioning. The YY.MM part of the version are used as a combined SemVer major version. That is, for new releases, the API of the library remains the same as it did in October 2015. Dependent code written since then is safe to upgrade. We will see the year and month segments update next time there is a breaking API change.

Other notable projects

boltons - YY.MINOR.MICRO - A broad library of utilities supplementing the Python standard library.
certifi - YYYY.MM.DD - certifi is a wrapper around Mozilla's certificate authority bundle, used for secure Internet communication. Similar to the IANA timezone database, certificate updates do not follow a fixed schedule, but timely, dateable updates are critical to security.
fusefs-ntfs - YYYY.MM.DD_MICRO - One of the earliest and most cross-compatible NTFS access layers for Unix systems.
LibreOffice - YY.MM - free and powerful office suite, and a successor to OpenOffice.org (commonly known as OpenOffice).
OpenSCAD - YYYY.0M - The premiere open-source offering for solid 3D CAD modelling.
pip - YY.MINOR.MICRO - Official package manager for Python.
PyCharm - YYYY.MINOR.MICRO - A leading Python IDE.
Stripe's API- YYYY-MM-DD - An API-first payments processing platform.
Unity - YYYY.MINOR.MICRO - Cross-platform game engine.

See the Users page for a growing list of CalVer users.

When to use CalVer

If both you and people you don't know use your project seriously, then use a serious version. Luckily, the decision on whether to use CalVer for that version is easier than ever:

Does your project feature a large or constantly-changing scope?
Large systems and frameworks, like Ubuntu and Twisted.
Amorphous sets of utilities, like Boltons.
Is your project time-sensitive in any way? Do other external changes drive new project releases?
Business requirements, such as Ubuntu's focus on support schedules.
Security updates, such as certifi's need to update certificates.
Political shifts, such as the IANA database's handling of timezone changes.

If you answered yes to any of these questions, CalVer's semantics make it a strong choice for your project.

Controle de versão do calendário

2019-07-01T07:00:00Z

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.

Contents

Esquema
Estudos de caso
Quando utilizar o CalVer

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.