We need to specify what is a release, what is an LTR, and we need to specify how
to construct version name, in order to name correctly versions, and to produce
zip packages and docker image correctly. Specifications should be clear and
simple, so users can decide easily which version they can install, and they can
know when they must upgrade.
Given a version number MAJOR.MINOR.PATCH, increment the:
MAJOR version when the product has incompatible API changes (deprecated api
have been removed, some existing API signatures have changed etc), and major
improvement that change how to use or install the software
MINOR version when some functionalities in a backwards compatible manner have been added.
PATCH version when there are only some backwards compatible bug fixes,
or minor improvements that do not change anything.
Additional labels for pre-release ( -alpha, -beta, -rc etc.) and build
metadata (+20191111 etc) are available as extensions to the MAJOR.MINOR.PATCH format.
Releases
A release is a stable version of Lizmap. It have a version number without a pre-release part.
Each minor version has its own branch into the repository, named RELEASE_<MAJOR>_<MINOR>,
in which the version is maintained, and from which patch version are released.
Except if it is a Long Term Release (see below), a minor version MAJOR.MINOR is
maintained until there are two minor versions released after it. Ex: the
maintenance of 3.3 will be stopped after the release of 3.4 and 3.5.
LTR
A Long Term Release, is a branch of Lizmap that is maintained for two years.
A LTR can be the latest minor version of a major release, or a version that
support specific features, for example a LTR version of Qgis (like Lizmap 3.2). So there could be several LTR that are supported at the same time.
There is no specific syntax version for LTR. The version is just
MAJOR.MINOR.PATCH. In texts, it can be followed by the LTR word. ex: 3.2 LTR.
Aliases
For docker or downloaded sites, we may need some aliases, so a user can always retrieve
a type of release.
latest is the alias for the latest stable version of Lizmap
latest-ltr is the alias for the latest stable LTR version
MAJOR.MINOR is the alias for the latest stable version of the branch MAJOR.MINOR
MAJOR.MINOR-ltr is the alias for the the latest stable version of the branch MAJOR.MINOR that is a LTR branch
MAJOR.MINOR-dev is the alias for the latest build of the branch MAJOR.MINOR
MAJOR.MINOR.PATCH-dev is the alias for the latest build of the next version MAJOR.MINOR.PATCH in the branch MAJOR.MINOR
Version for developments
By definition, a version in development has no version. And as Semver defines
the precedence by alphanumeric order, in the pre-release part
of the version, we cannot use suffix like -pre, -dev...
The version indicated into Lizmap should always be the next version in development.
For builds and packages of a development version, names of packages/builds may contain the next version number, followed by a -dev suffix.
Version storage
The version must be indicated into a file of the source code, typically into
lizmap/project.xml.
The LTR status should be also indicated somewhere in the source code, typically into
lizmap/project.xml.
Example of a normal version:
<version date="2019-11-12">1.2.3</version>
Example of a LTR version, here indicated into a ltr attribute with
the end date of the support of the branch:
pcav
commented
4 years ago
Lizmap RFC: Versioning for releases & LTR
Date 2019/11/11
Author Laurent Jouanneau (@laurentj )
maintainer @laurentj
Version All
Summary
We need to specify what is a release, what is an LTR, and we need to specify how to construct version name, in order to name correctly versions, and to produce zip packages and docker image correctly. Specifications should be clear and simple, so users can decide easily which version they can install, and they can know when they must upgrade.
Version number
The version number must follow the semver specification. In summary:
Given a version number
MAJOR.MINOR.PATCH, increment the:MAJORversion when the product has incompatible API changes (deprecated api have been removed, some existing API signatures have changed etc), and major improvement that change how to use or install the softwareMINORversion when some functionalities in a backwards compatible manner have been added.PATCHversion when there are only some backwards compatible bug fixes, or minor improvements that do not change anything.Additional labels for pre-release (
-alpha,-beta,-rcetc.) and build metadata (+20191111etc) are available as extensions to the MAJOR.MINOR.PATCH format.Releases
A release is a stable version of Lizmap. It have a version number without a pre-release part.
Each minor version has its own branch into the repository, named
RELEASE_<MAJOR>_<MINOR>, in which the version is maintained, and from which patch version are released.Except if it is a Long Term Release (see below), a minor version
MAJOR.MINORis maintained until there are two minor versions released after it. Ex: the maintenance of3.3will be stopped after the release of3.4and3.5.LTR
A Long Term Release, is a branch of Lizmap that is maintained for two years.
A LTR can be the latest minor version of a major release, or a version that support specific features, for example a LTR version of Qgis (like Lizmap 3.2). So there could be several LTR that are supported at the same time.
There is no specific syntax version for LTR. The version is just
MAJOR.MINOR.PATCH. In texts, it can be followed by theLTRword. ex:3.2 LTR.Aliases
For docker or downloaded sites, we may need some aliases, so a user can always retrieve a type of release.
latestis the alias for the latest stable version of Lizmaplatest-ltris the alias for the latest stable LTR versionMAJOR.MINORis the alias for the latest stable version of the branchMAJOR.MINORMAJOR.MINOR-ltris the alias for the the latest stable version of the branchMAJOR.MINORthat is a LTR branchMAJOR.MINOR-devis the alias for the latest build of the branchMAJOR.MINORMAJOR.MINOR.PATCH-devis the alias for the latest build of the next versionMAJOR.MINOR.PATCHin the branchMAJOR.MINORVersion for developments
By definition, a version in development has no version. And as Semver defines the precedence by alphanumeric order, in the pre-release part of the version, we cannot use suffix like
-pre,-dev...The version indicated into Lizmap should always be the next version in development.
For builds and packages of a development version, names of packages/builds may contain the next version number, followed by a
-devsuffix.Version storage
The version must be indicated into a file of the source code, typically into lizmap/project.xml.
The LTR status should be also indicated somewhere in the source code, typically into lizmap/project.xml.
Example of a normal version:
Example of a LTR version, here indicated into a
ltrattribute with the end date of the support of the branch:Votes
(required)