calver.org Open in urlscan Pro
172.105.157.204  Public Scan

Form analysis
0 forms found in the DOM

Text Content

CALVER

Timely Project Versioning

About Users 中文 pt-BR GitHub

--------------------------------------------------------------------------------


CALENDAR VERSIONING





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
   * Ubuntu
   * Twisted
   * youtube-dl
   * The IANA/Olson timezone database
   * Teradata
   * Other notable projects
 * 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.



--------------------------------------------------------------------------------

July 1, 2019

PREVIOUSLY

Controle de versão do calendário

© 2020