You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
239 lines
14 KiB
239 lines
14 KiB
HAProxy branches and life cycle
|
|
===============================
|
|
|
|
The HAProxy project evolves quickly to stay up to date with modern features
|
|
found in web environments but also takes a great care of addressing bugs which
|
|
may affect deployed versions without forcing such users to upgrade when not
|
|
needed. For this reason the project is developed in branches.
|
|
|
|
A branch is designated as two numbers separated by a dot, for example "1.8".
|
|
This numbering is historical. Each new development cycle increases the second
|
|
digit by one, and after it reaches '9' it goes back to zero and the first digit
|
|
increases by one. It effectively grows as a decimal number increased by 0.1 per
|
|
version.
|
|
|
|
The complete version is made of the branch suffixed with "-dev" followed by a
|
|
sequence number during development, then by "." followed by a number when the
|
|
development of that branch is finished and the branch enters a maintenance
|
|
phase. The first release of a branch starts at ".0". Immediately after ".0" is
|
|
issued, the next branch is created as "-dev0" as an exact copy of the previous
|
|
branch's ".0" version. Thus we observe the following development sequence:
|
|
|
|
... 1.9-dev10 -> 1.9-dev11 -> 1.9.0 -> 2.0-dev0 -> 2.0-dev1 ... 2.0 -> ...
|
|
|
|
Occasionally a series of "-rc" versions may be emitted between the latest -dev
|
|
and the release to mark the end of development and start of stabilizing, though
|
|
it's mostly a signal send to users that the release is approaching rather than
|
|
a change in the cycle as it is always hard to categorize patches.
|
|
|
|
Very often the terms "branch" and "version" will be used interchangeably with
|
|
only the first two digits to designate "the latest version of that branch". So
|
|
when someone asks you "Could you please try the same on 1.8", it means "1.8.X"
|
|
with X as high as possible, thus for example 1.8.20 if this one is available at
|
|
this moment.
|
|
|
|
During the maintenance phase, a maintenance branch is created for the just
|
|
released version. The development version remains in the development branch
|
|
called "master", or sometimes "-dev". If branches are represented vertically
|
|
and time horizontally, this will look like this:
|
|
|
|
versions branch
|
|
1.9-dev10 1.9-dev11 1.9.0 2.0-dev0 2.0-dev1 2.0-dev2
|
|
----+--------+---------+-------+---------+---------+----------> master
|
|
\
|
|
\ 1.9.1 1.9.2
|
|
`-----------+-------------+---------> 1.9
|
|
|
|
Each released version (e.g. 1.9.0 above) appears once in the master branch so
|
|
that it is easy to list history of changes between versions.
|
|
|
|
Before version 1.4, development and maintenance were inter-mixed in the same
|
|
branch, which resulted in latest maintenance branches becoming unstable after
|
|
some point. This is why versions 1.3.14 and 1.3.15 became maintenance branches
|
|
on their own while the development pursued on 1.3 to stabilize again in the
|
|
latest versions.
|
|
|
|
Starting with version 1.4.0, a rule has been set not to create new features
|
|
into a maintenance branch. It was not well respected and still created trouble
|
|
with certain 1.4 versions causing regressions and confusing users.
|
|
|
|
Since 1.5.0 this "no new feature" rule has become strict and maintenance
|
|
versions only contain bug fixes that are necessary in this branch. This means
|
|
that any version X.Y.Z is necessarily more stable than X.Y.W with W<Z.
|
|
|
|
For this reason there is absolutely no excuse for not updating a version within
|
|
your branch, as your version necessarily contains bugs that are fixed in any
|
|
later version in that same branch. Obviously when a branch is just released,
|
|
there will be some occasional bugs. And once in a while a fix for a recently
|
|
discovered bug may have an undesired side effect called a regression. This must
|
|
never happen but this will happen from time to time, especially on recently
|
|
released versions. This is often presented as an excuse by some users for not
|
|
updating but this is wrong, as the risk staying with an older version is much
|
|
higher than the risk of updating. If you fear there could be an issue with an
|
|
update because you don't completely trust the version in your branch, it simply
|
|
means you're using the wrong branch and need an older one.
|
|
|
|
When a bug is reported in a branch, developers will systematically ask if the
|
|
bug is present in the latest version of this branch (since developers don't
|
|
like to work on bugs that were already fixed). It's a good practice to perform
|
|
the update yourself and to test again before reporting the bug. Note, as long
|
|
as you're using a supported branch, as indicated on the haproxy.org web site,
|
|
you don't need to upgrade to another branch to report a bug. However from time
|
|
to time it may happen that a developer will ask you if you can try it in order
|
|
to help narrow the problem down. But this will never be a requirement, just a
|
|
question.
|
|
|
|
Once a bug is understood, it is tested on the development branch and fixed
|
|
there. Then the fix will be applied in turn to older branches, jumping from
|
|
one to the other in descending order. For example:
|
|
|
|
FIX
|
|
2.0-dev4 HERE 2.0-dev5 2.0-dev6
|
|
-----+-------V-------------+-----------+--------------> master
|
|
1.9.4 \ 1.9.5 1.9.6 1.9.7
|
|
--+------------o-------+---------+-------------+------> 1.9
|
|
1.8.18 \ 1.8.19 1.8.20
|
|
-----+-----------o------------+-------------+---------> 1.8
|
|
|
|
This principle ensures that you will always have a safe upgrade path from an
|
|
older branch to a newer: under no circumstances a bug that was already fixed
|
|
in an older branch will still be present in a newer one. In the diagram above,
|
|
a bug reported for 1.8.18 would be fixed between 2.0-dev4 and 2.0-dev5. The
|
|
fix will be backported into 1.9 and from there into 1.8. 1.9.5 will be issued
|
|
with the fix before 1.8.19 will be issued. This guarantees that for any version
|
|
1.8 having the fix, there always exists a version 1.9 with it as well. So if
|
|
you would upgrade to 1.8.19 to benefit from the fix and the next day decide
|
|
that for whatever new feature you need to upgrade to 1.9, you'll have 1.9.5
|
|
available with the same set of fixes so you will not reintroduce a previously
|
|
fixed problem.
|
|
|
|
In practice, it takes longer to release older versions than newer ones. There
|
|
are two reasons to this. One is technical: the fixes often require some
|
|
adaptations to be done for older versions. The other reason is stability: in
|
|
spite of the great care and the tests, there is always a faint risk that a fix
|
|
introduces a regression. By leaving fixes exposed in more recent versions
|
|
before appearing in older ones, there is a much smaller probability that such a
|
|
regression remains undetected when the next version of the older branch is
|
|
issued.
|
|
|
|
So the rule for the best stability is very simple:
|
|
|
|
STICK TO THE BRANCH THAT SUITS YOUR NEEDS AND APPLY ALL UPDATES.
|
|
|
|
With other projects, some people developed a culture of backporting only a
|
|
selection of fixes into their own maintenance branch. Usually they consider
|
|
these fixes are critical, or security-related only. THIS IS TERRIBLY WRONG.
|
|
It is already very difficult for the developers who made the initial patch to
|
|
figure if and how it must be backported to an older branch, what extra patches
|
|
it depends on to be safe, as you can imagine it is impossible for anyone else
|
|
to make a safe guess about what to pick.
|
|
|
|
A VERSION WHICH ONLY CONTAINS A SELECTION OF FIXES IS WAY MORE
|
|
DANGEROUS AND LESS STABLE THAN ONE WITHOUT ANY OF THESE FIXES.
|
|
|
|
Branches up to 1.8 are all designated as "long-term supported" ("LTS" for
|
|
short), which means that they are maintained for several years after the
|
|
release. These branches were emitted at a pace of one per year since 1.5 in
|
|
2014. As of 2019, 1.5 is still supported and widely used, eventhough it very
|
|
rarely receives updates. After a few years these LTS branches enter a
|
|
"critical fixes only" status, which means that they will rarely receive a fix
|
|
but if that a critital issue affects them, a release will be made, with or
|
|
without any other fix. Once a version is not supported anymore, it will not
|
|
receive any fix at all and it will really be time for you to upgrade to a more
|
|
recent branch. Please note that even when an upgrade is needed, a great care is
|
|
given to backwards compatibility so that most configs written for version 1.1
|
|
still work with little to no modification 16 years later on version 2.0.
|
|
|
|
Since 1.9, the release pacing has increased to match faster moving feature sets
|
|
and a faster stabilization of the technical foundations. The principle is now
|
|
the following:
|
|
- one release is emitted between October and December, with an odd version
|
|
number (such as "1.9"). This version heavily focuses on risky changes that
|
|
are considered necessary to develop new features. It can for example bring
|
|
nice performance improvements as well as invisible changes that will serve
|
|
later ; these versions will only be emitted for developers and highly
|
|
skilled users. They will not be maintained for a long time, they will
|
|
receive updates for 12 to 18 months only after which they will be marked
|
|
End-Of-Life ("EOL" for short). They may receive delicate fixes during their
|
|
maintenance cycle so users have to be prepared to see some breakage once in
|
|
a while as fixes are stabilizing. THESE VERSIONS MUST ABSOLUTELY NOT BE
|
|
PACKAGED BY OPERATING SYSTEM VENDORS.
|
|
|
|
- one release is emitted between May and June, with an even version number
|
|
(such as "2.0"). This version mostly relies on the technical foundations
|
|
brought by the previous release and tries hard not to apply risky changes.
|
|
Instead it will bring new user-visible features. Such versions will be
|
|
long-term supported and may be packaged by operating system vendors.
|
|
|
|
This development model provides better stability for end users and better
|
|
feedback for developers:
|
|
- regular users stick to LTS versions which rely on the same foundations
|
|
as the previous releases that had 6 months to stabilize. In terms of
|
|
stability it really means that the point zero version already accumulated
|
|
6 months of fixes and that it is much safer to use even just after it is
|
|
released.
|
|
|
|
- for developers, given that the odd versions are solely used by highly
|
|
skilled users, it's easier to get advanced traces and captures, and there
|
|
is less pressure during bug reports because there is no doubt the user is
|
|
autonomous and knows how to work around the issue or roll back to the last
|
|
working version.
|
|
|
|
Thus the release cycle from 1.8 to 2.2 should look like this:
|
|
|
|
1.8.0 1.9.0 2.0.0 2.1.0 2.2.0
|
|
--+---------------+---------------+--------------+--------------+----> master
|
|
\ \ \ \ \
|
|
\ \ \ \ `--> 2.2 LTS
|
|
\ \ \ `--+--+--+---+---> 2.1
|
|
\ \ `----+-----+------+-------+----> 2.0 LTS
|
|
\ `--+-+-+--+---+------+--------+-----| EOL 1.9
|
|
`---+---+---+-----+-------+-----------+---------------+------> 1.8 LTS
|
|
|
|
In short the non-LTS odd releases can be seen as technological previews of the
|
|
next feature release, and will be terminated much earlier. The plan is to barely
|
|
let them overlap with the next non-LTS release, allowing advanced users to
|
|
always have the choice between the last two major releases.
|
|
|
|
With all this in mind, what version should you use ? It's quite simple:
|
|
- if you're a first-time HAProxy user, just use the version provided by your
|
|
operating system. Just take a look at the "known bugs" section on the
|
|
haproxy.org web site to verify that it's not affected by bugs that could
|
|
have an impact for you.
|
|
|
|
- if you don't want or cannot use the version shipped with your operating
|
|
system, it is possible that other people (including the package maintainer)
|
|
provide alternate versions. This is the case for Debian and Ubuntu for
|
|
example, where you can choose your distribution and pick the branch you
|
|
need here: https://haproxy.debian.net/
|
|
|
|
- if you want to build with specific options, apply some patches, you'll
|
|
have to build from sources. If you have little experience or are not
|
|
certain to devote regular time to perform this task, take an "old" branch
|
|
(i.e. 1-2 years old max, for example 1.8 when 2.0 is emitted). You'll avoid
|
|
most bugs and will not have to work too often to update your local version.
|
|
|
|
- if you need a fresh version for application development, or to benefit from
|
|
latest improvements, take the most recent version of the most recent branch
|
|
and keep it up to date. You may even want to use the Git version or nightly
|
|
snapshots.
|
|
|
|
- if you want to develop on HAProxy, use the master from the Git tree.
|
|
|
|
- if you want to follow HAProxy's development by doing some tests without
|
|
the burden of entering too much into the development process, just use the
|
|
-dev versions of the master branch. At some point you'll feel the urge to
|
|
switch to the Git version anyway as it will ultimately simplify your work.
|
|
|
|
- if you're installing it on unmanaged servers with little to no hostile
|
|
exposure, or your home router, you should pick the latest version in one
|
|
of the oldest supported branches. While it doesn't guarantee that you will
|
|
never have to upgrade it, at least as long as you don't use too complex a
|
|
setup, it's unlikely that you will need to update it often.
|
|
|
|
And as a general rule, do not put a non-LTS version on a server unless you are
|
|
absolutely certain you are going to keep it up to date yourself and already
|
|
plan to replace it once the following LTS version is issued. If you are not
|
|
going to manage updates yourself, use pre-packaged versions exclusively and do
|
|
not expect someone else to have to deal with the burden of building from
|
|
sources.
|
|
|