Skip to content

Update release policy page #1447

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Sep 8, 2020
Merged

Update release policy page #1447

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
058edf7
Initial draft
veod32 Aug 4, 2020
aff3ad1
Add table with all release versions
veod32 Aug 5, 2020
1c9ec4e
Final revision
veod32 Aug 7, 2020
060e3f7
Fix after review
veod32 Aug 11, 2020
64ce3ab
Corrections after 2nd review
veod32 Sep 4, 2020
b4fc194
Correction after review (3)
veod32 Sep 8, 2020
984078f
Update doc/dev_guide/release_management.rst
veod32 Sep 8, 2020
7bb1857
Update doc/dev_guide/release_management.rst
veod32 Sep 8, 2020
f1fb11c
Update doc/dev_guide/release_management.rst
veod32 Sep 8, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
236 changes: 138 additions & 98 deletions doc/dev_guide/release_management.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,92 +10,166 @@ Release management
Release policy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A Tarantool release is identified by three digits, for example, 1.7.7.
We use these digits according to their definitions provided at http://semver.org:
A Tarantool release is identified by three digits, for example, 1.10.7:

* The first digit stands for a MAJOR release series that introduces
some *major changes*. Up to now, there has been only one major release jump
when we delivered the 2.x release series with the SQL support.
* The second digit stands for a MINOR release series that is used for
introducing new *features*. :ref:`Backward incompatible changes <backward-incompatible>`
are possible between these release series.
* The third digit is for PATCH releases by which we reflect how stable
the MINOR release series is:

* ``0`` meaning **alpha**
* ``1`` meaning **beta**
* ``2`` and above meaning **stable**.

So, each MINOR release series goes through a development-maturity life cycle
as follows:

1. **Alpha**. Once a quarter, we start off with a new alpha version,
such as 2.3.0, 2.4.0, and so on. This is not what an alpha release usually
means in the typical software release life cycle but rather the current trunk
version which is under heavy development and can be unstable.
The current alpha version always lives in the master branch.

2. **Beta**. When all the features planned are implemented, we fork a new branch
from the master branch and tag it as a new beta version.
It contains ``1`` for the PATCH digit, e.g., 2.3.1, 2.4.1, and so on.
This version cannot be called stable yet (feature freeze has just been done)
although there're no known critical regressions in it since
the last stable release.

3. **Stable**. Finally, after we see our beta version runs successfully in
a production or development environment during another quarter while we fix
incoming bugs, we declare this version stable. It is tagged with ``2`` for
the PATCH digit, e.g., 2.3.2, 2.4.2, and so on.

We support such version for 3 months while making another stable release
by fixing all bugs found. We release it in a quarter. This last tag
contains ``3`` for the PATCH digit, e.g., 2.3.3, 2.4.3, and so on.
After the tag is set, no new changes are allowed to the release branch,
and it is declared deprecated and superseded by a newer MINOR version.

Stable versions don't receive any new features and only get backward
compatible fixes.

Like Ubuntu, in terms of support, we distinguish between two kinds of stable
release series:

* **LTS (Long Term Support)** is a release series that is supported
for 3 years (community) and up to 5 years (paying customers).
Current LTS release series is 1.10, and it receives only PATCH level
releases.

* The first digit stands for MAJOR release. A **major** release may contain
*incompatible changes*.
* The second digit stands for MINOR release, it does not contain incompatible
changes, and is used for introducing backward-compatible *features*.
* The third digit is for PATCH releases that contain only backward-compatible
*bug fixes*.
* **Standard** is a release series that is supported only for a few months
until the next release series enters the stable state.

In MINOR digit, we reflect how stable a release is:
Below is a diagram that illustrates the release sequence issuing described above
by an example of some latest releases and release series:

* 0 meaning alpha,
* 1 meaning beta,
* anything between 1 and 10 meaning stable, and
* 10 meaning LTS.
.. _release-diagram:

So, each MAJOR release series goes through a development-maturity life cycle of
MINOR releases, as follows:
.. code-block::

1. **Alpha**. Once in every few months we release a few alpha versions,
e.g. 2.0.1, 2.0.2.

Alpha versions may contain incompatible changes, crashes and other bugs.
1.10 series -- 1.10.4 -- 1.10.5 -- 1.10.6 -- 1.10.7
(LTS)

2. **Beta**. Once major changes necessary to introduce new flagship features
are ready, we release a few beta versions, e.g. 2.1.3, 2.1.4.
....

Beta versions may contain crashes, but do not have incompatible changes,
so can be used to develop new applications.
2.2 series --- 2.2.1 --- 2.2.2 --- 2.2.3 (end of support)
|
V
2.3 series ... 2.3.0 --- 2.3.1 --- 2.3.2 --- 2.3.3 (end of support)
|
V
2.4 series ............. 2.4.0 --- 2.4.1 --- 2.4.2
|
V
2.5 series ....................... 2.5.0 --- 2.5.1
|
V
2.6 series ................................. 2.6.0

4. **Stable**. Finally, after we see our beta versions run successfully in
production, usually in a few more months, during which we fix all incoming
bugs and add some minor features, we declare this MAJOR release series
stable.
-----------------|---------|---------|---------|------> (time)
1/4 yr. 1/4 yr. 1/4 yr.

Like Ubuntu, we distinguish two kinds of stable releases:
*Support* means that we continue fixing bugs. We add bug fixes simultaneously
into the following release series: LTS, last stable, beta, and alpha.
If we look at the release diagram above, it means that the bug fixes are to be
added into 1.10, 2.4, 2.5, and 2.6 release series.

* **LTS (Long Term Support)** releases that are supported for 3 years
(community) and up to 5 years (paying customers). **LTS** release
is identified by MINOR version 10.
* **Standard stable releases** are only supported a few months after the next
stable is out.
To sum it up, once a quarter we release (see the release diagram above for
reference):

"Support" means that we continue fixing bugs in a release.
* next LTS release, e.g., 1.10.7
* two stable releases, e.g., 2.3.3 and 2.4.2
* beta version of the next release series, e.g., 2.5.1.

We add commits simultaneously to three MAJOR releases:
In all supported releases, when we find and fix an outstanding CVE/vulnerability,
we deliver a patch for that but do not tag a new PATCH level version.
Users will be informed about such critical patches via the official Tarantool news
channel (`tarantool_news <https://t.me/tarantool_news>`_).

* **LTS** is a stable release which does not receive new features, and only gets
backward compatible fixes. Hence, following the rules of semver, LTS release
never has its MAJOR or MINOR version increased, and only gets PATCH level
releases.
We also publish nightly builds, and use the fourth slot in the version
identifier to designate the nightly build number.

* **STABLE** is our current stable release, which may receive new features.
When the next STABLE version is published, MINOR version is incremented.
Between MINOR releases, we may have intermediate PATCH level releases as well,
which will contain only bug fixes. We maintain PATCH level releases for
two STABLE releases, the current and the previous one, to preserve support
continuity.
.. _backward-incompatible:

* **NEXT** is our next MAJOR release, and it follows the maturity
cycle described in the beginning. While NEXT release is in alpha state,
its MINOR is frozen at 0 and is only increased when the release reaches
BETA status. Once the NEXT release becomes STABLE, we switch the vehicle for
delivery of minor features, designating the previous stable release as LTS,
and releasing it with MINOR set to 10.
.. note::

To sum up, once a quarter we release:
A release series may introduce backward incompatible changes in a sense that
existing Lua, SQL or C code that are run on a current release series
may not be run with the same effect on a future series.
However, we don't exploit this rule and don't make incompatible changes
without appropriate reason. We usually deliver information how mature
a functionality is via release notes.

* the next LTS release, e.g. 2.10.6, 2.10.7 or 2.10.8
* the next STABLE release, e.g. 3.6, 3.7 or 3.8
* (optionally) an alpha or beta version of the NEXT release,
e.g. 4.0.1, 4.0.2 or 4.0.3
Please note that binary data layout
is always compatible with the previous series as well as with the LTS series
(an instance of ``X.Y`` version can be started on top of ``X.(Y+1)``
or ``1.10.z`` data); binary protocol is compatible too
(client-server as well as replication protocol).

In all supported releases, we also release a PATCH release as soon as we
find and fix an outstanding CVE/vulnerability.
.. _release-list:

We also publish nightly builds, and use the fourth slot in the version
identifier to designate the nightly build number.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Release list
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Example version identifier:
Below is the table containing all Tarantool releases starting from 1.10.0 up to
the current latest versions (as of September 1, 2020). For each release series,
releases are sorted out as alpha, beta, and stable ones.

+---------+--------+--------+--------+
| Release | Alpha | Beta | Stable |
| series | | | |
+=========+========+========+========+
| 1.10 | 1.10.0 | 1.10.1 | 1.10.2 |
| (LTS) | | | 1.10.3 |
| | | | 1.10.4 |
| | | | 1.10.5 |
| | | | 1.10.6 |
| | | | 1.10.7 |
+---------+--------+--------+--------+
| 2.1 | 2.1.0 | 2.1.1 | 2.1.2 |
| | | | 2.1.3 |
+---------+--------+--------+--------+
| 2.2 | 2.2.0 | 2.2.1 | 2.2.2 |
| | | | 2.2.3 |
+---------+--------+--------+--------+
| 2.3 | 2.3.0 | 2.3.1 | 2.3.2 |
| | | | 2.3.3 |
+---------+--------+--------+--------+
| 2.4 | 2.4.0 | 2.4.1 | 2.4.2 |
+---------+--------+--------+--------+
| 2.5 | 2.5.0 | 2.5.1 | |
+---------+--------+--------+--------+
| 2.6 | 2.6.0 | | |
+---------+--------+--------+--------+

* 2.0.3 - third alpha of 2.0 release
* 2.1.3 - a beta of 2.0 release
* 2.2 - a stable version of 2.0 series, but not an LTS yet
* 2.10 - an LTS release

.. _release-minor:

Expand Down Expand Up @@ -161,37 +235,3 @@ Also, don't forget this:

2. Click 'Release milestone'. Create a milestone for the next minor release.
Alert the driver to target bugs and blueprints to the new milestone.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
How to release a Docker container
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To bump a new version of a Docker container:

1. On the ``master`` branch of
`tarantool/docker <https://github.com/tarantool/docker>`_ repository,
find the Dockerfile that corresponds to the commit's **major** version (e.g.
https://github.com/tarantool/docker/blob/master/2.x/Dockerfile
for Tarantool version 2.4) and specify the required commit in
``TARANTOOL_VERSION``, for example
``TARANTOOL_VERSION=2.4.0-11-gcd17b77f9``.

Commit the Dockerfile back to ``master`` branch.

3. In the same repository, create a branch named after the commit's
``<major>.<minor>`` versions,
e.g. branch ``2.4`` for commit 2.4.0-11-gcd17b77f9.

4. In Tarantool container build settings at ``hub.docker.com``
(https://hub.docker.com/r/tarantool/tarantool/~/settings/automated-builds/),
add a new line:

.. code-block:: text

Branch: x.y, /x, x.y

where ``x`` and ``y`` correspond to the commit's major and minor versions.

Click **Save changes**.

Shortly after, a new Docker container will be built.