blob: 53b2ee99619672cf904711afd7b6524c49341b6e [file] [log] [blame]
Willy Tarreauba4ad172019-06-15 21:53:40 +02001HAProxy branches and life cycle
2===============================
3
4The HAProxy project evolves quickly to stay up to date with modern features
5found in web environments but also takes a great care of addressing bugs which
6may affect deployed versions without forcing such users to upgrade when not
7needed. For this reason the project is developed in branches.
8
9A branch is designated as two numbers separated by a dot, for example "1.8".
10This numbering is historical. Each new development cycle increases the second
11digit by one, and after it reaches '9' it goes back to zero and the first digit
12increases by one. It effectively grows as a decimal number increased by 0.1 per
13version.
14
15The complete version is made of the branch suffixed with "-dev" followed by a
16sequence number during development, then by "." followed by a number when the
17development of that branch is finished and the branch enters a maintenance
18phase. The first release of a branch starts at ".0". Immediately after ".0" is
19issued, the next branch is created as "-dev0" as an exact copy of the previous
20branch's ".0" version. Thus we observe the following development sequence:
21
22 ... 1.9-dev10 -> 1.9-dev11 -> 1.9.0 -> 2.0-dev0 -> 2.0-dev1 ... 2.0 -> ...
23
24Occasionally a series of "-rc" versions may be emitted between the latest -dev
25and the release to mark the end of development and start of stabilizing, though
26it's mostly a signal send to users that the release is approaching rather than
27a change in the cycle as it is always hard to categorize patches.
28
29Very often the terms "branch" and "version" will be used interchangeably with
30only the first two digits to designate "the latest version of that branch". So
31when someone asks you "Could you please try the same on 1.8", it means "1.8.X"
32with X as high as possible, thus for example 1.8.20 if this one is available at
33this moment.
34
35During the maintenance phase, a maintenance branch is created for the just
36released version. The development version remains in the development branch
37called "master", or sometimes "-dev". If branches are represented vertically
38and time horizontally, this will look like this:
39
40 versions branch
41 1.9-dev10 1.9-dev11 1.9.0 2.0-dev0 2.0-dev1 2.0-dev2
42 ----+--------+---------+-------+---------+---------+----------> master
43 \
44 \ 1.9.1 1.9.2
45 `-----------+-------------+---------> 1.9
46
47Each released version (e.g. 1.9.0 above) appears once in the master branch so
48that it is easy to list history of changes between versions.
49
50Before version 1.4, development and maintenance were inter-mixed in the same
51branch, which resulted in latest maintenance branches becoming unstable after
52some point. This is why versions 1.3.14 and 1.3.15 became maintenance branches
53on their own while the development pursued on 1.3 to stabilize again in the
54latest versions.
55
56Starting with version 1.4.0, a rule has been set not to create new features
57into a maintenance branch. It was not well respected and still created trouble
58with certain 1.4 versions causing regressions and confusing users.
59
60Since 1.5.0 this "no new feature" rule has become strict and maintenance
61versions only contain bug fixes that are necessary in this branch. This means
62that any version X.Y.Z is necessarily more stable than X.Y.W with W<Z.
63
64For this reason there is absolutely no excuse for not updating a version within
65your branch, as your version necessarily contains bugs that are fixed in any
66later version in that same branch. Obviously when a branch is just released,
67there will be some occasional bugs. And once in a while a fix for a recently
68discovered bug may have an undesired side effect called a regression. This must
69never happen but this will happen from time to time, especially on recently
70released versions. This is often presented as an excuse by some users for not
71updating but this is wrong, as the risk staying with an older version is much
72higher than the risk of updating. If you fear there could be an issue with an
73update because you don't completely trust the version in your branch, it simply
74means you're using the wrong branch and need an older one.
75
76When a bug is reported in a branch, developers will systematically ask if the
77bug is present in the latest version of this branch (since developers don't
78like to work on bugs that were already fixed). It's a good practice to perform
79the update yourself and to test again before reporting the bug. Note, as long
80as you're using a supported branch, as indicated on the haproxy.org web site,
81you don't need to upgrade to another branch to report a bug. However from time
82to time it may happen that a developer will ask you if you can try it in order
83to help narrow the problem down. But this will never be a requirement, just a
84question.
85
86Once a bug is understood, it is tested on the development branch and fixed
87there. Then the fix will be applied in turn to older branches, jumping from
88one to the other in descending order. For example:
89
90 FIX
91 2.0-dev4 HERE 2.0-dev5 2.0-dev6
92 -----+-------V-------------+-----------+--------------> master
93 1.9.4 \ 1.9.5 1.9.6 1.9.7
94 --+------------o-------+---------+-------------+------> 1.9
95 1.8.18 \ 1.8.19 1.8.20
96 -----+-----------o------------+-------------+---------> 1.8
97
98This principle ensures that you will always have a safe upgrade path from an
99older branch to a newer: under no circumstances a bug that was already fixed
100in an older branch will still be present in a newer one. In the diagram above,
101a bug reported for 1.8.18 would be fixed between 2.0-dev4 and 2.0-dev5. The
102fix will be backported into 1.9 and from there into 1.8. 1.9.5 will be issued
103with the fix before 1.8.19 will be issued. This guarantees that for any version
1041.8 having the fix, there always exists a version 1.9 with it as well. So if
105you would upgrade to 1.8.19 to benefit from the fix and the next day decide
106that for whatever new feature you need to upgrade to 1.9, you'll have 1.9.5
107available with the same set of fixes so you will not reintroduce a previously
108fixed problem.
109
110In practice, it takes longer to release older versions than newer ones. There
111are two reasons to this. One is technical: the fixes often require some
112adaptations to be done for older versions. The other reason is stability: in
113spite of the great care and the tests, there is always a faint risk that a fix
114introduces a regression. By leaving fixes exposed in more recent versions
115before appearing in older ones, there is a much smaller probability that such a
116regression remains undetected when the next version of the older branch is
117issued.
118
119So the rule for the best stability is very simple:
120
121 STICK TO THE BRANCH THAT SUITS YOUR NEEDS AND APPLY ALL UPDATES.
122
123With other projects, some people developed a culture of backporting only a
124selection of fixes into their own maintenance branch. Usually they consider
125these fixes are critical, or security-related only. THIS IS TERRIBLY WRONG.
126It is already very difficult for the developers who made the initial patch to
127figure if and how it must be backported to an older branch, what extra patches
128it depends on to be safe, as you can imagine it is impossible for anyone else
129to make a safe guess about what to pick.
130
131 A VERSION WHICH ONLY CONTAINS A SELECTION OF FIXES IS WAY MORE
132 DANGEROUS AND LESS STABLE THAN ONE WITHOUT ANY OF THESE FIXES.
133
134Branches up to 1.8 are all designated as "long-term supported" ("LTS" for
135short), which means that they are maintained for several years after the
136release. These branches were emitted at a pace of one per year since 1.5 in
Thayne McCombsdab4ba62021-01-07 21:24:41 -07001372014. As of 2019, 1.5 is still supported and widely used, even though it very
Willy Tarreauba4ad172019-06-15 21:53:40 +0200138rarely receives updates. After a few years these LTS branches enter a
139"critical fixes only" status, which means that they will rarely receive a fix
140but if that a critital issue affects them, a release will be made, with or
141without any other fix. Once a version is not supported anymore, it will not
142receive any fix at all and it will really be time for you to upgrade to a more
143recent branch. Please note that even when an upgrade is needed, a great care is
144given to backwards compatibility so that most configs written for version 1.1
145still work with little to no modification 16 years later on version 2.0.
146
147Since 1.9, the release pacing has increased to match faster moving feature sets
148and a faster stabilization of the technical foundations. The principle is now
149the following:
150 - one release is emitted between October and December, with an odd version
151 number (such as "1.9"). This version heavily focuses on risky changes that
152 are considered necessary to develop new features. It can for example bring
153 nice performance improvements as well as invisible changes that will serve
154 later ; these versions will only be emitted for developers and highly
155 skilled users. They will not be maintained for a long time, they will
156 receive updates for 12 to 18 months only after which they will be marked
157 End-Of-Life ("EOL" for short). They may receive delicate fixes during their
158 maintenance cycle so users have to be prepared to see some breakage once in
159 a while as fixes are stabilizing. THESE VERSIONS MUST ABSOLUTELY NOT BE
160 PACKAGED BY OPERATING SYSTEM VENDORS.
161
162 - one release is emitted between May and June, with an even version number
163 (such as "2.0"). This version mostly relies on the technical foundations
164 brought by the previous release and tries hard not to apply risky changes.
165 Instead it will bring new user-visible features. Such versions will be
166 long-term supported and may be packaged by operating system vendors.
167
168This development model provides better stability for end users and better
169feedback for developers:
170 - regular users stick to LTS versions which rely on the same foundations
171 as the previous releases that had 6 months to stabilize. In terms of
172 stability it really means that the point zero version already accumulated
173 6 months of fixes and that it is much safer to use even just after it is
174 released.
175
176 - for developers, given that the odd versions are solely used by highly
177 skilled users, it's easier to get advanced traces and captures, and there
178 is less pressure during bug reports because there is no doubt the user is
179 autonomous and knows how to work around the issue or roll back to the last
180 working version.
181
182Thus the release cycle from 1.8 to 2.2 should look like this:
183
184 1.8.0 1.9.0 2.0.0 2.1.0 2.2.0
185 --+---------------+---------------+--------------+--------------+----> master
186 \ \ \ \ \
187 \ \ \ \ `--> 2.2 LTS
188 \ \ \ `--+--+--+---+---> 2.1
189 \ \ `----+-----+------+-------+----> 2.0 LTS
190 \ `--+-+-+--+---+------+--------+-----| EOL 1.9
191 `---+---+---+-----+-------+-----------+---------------+------> 1.8 LTS
192
193In short the non-LTS odd releases can be seen as technological previews of the
Ilya Shipitsin2075ca82020-03-06 23:22:22 +0500194next feature release, and will be terminated much earlier. The plan is to barely
Willy Tarreauba4ad172019-06-15 21:53:40 +0200195let them overlap with the next non-LTS release, allowing advanced users to
196always have the choice between the last two major releases.
197
198With all this in mind, what version should you use ? It's quite simple:
199 - if you're a first-time HAProxy user, just use the version provided by your
200 operating system. Just take a look at the "known bugs" section on the
201 haproxy.org web site to verify that it's not affected by bugs that could
202 have an impact for you.
203
204 - if you don't want or cannot use the version shipped with your operating
205 system, it is possible that other people (including the package maintainer)
206 provide alternate versions. This is the case for Debian and Ubuntu for
207 example, where you can choose your distribution and pick the branch you
208 need here: https://haproxy.debian.net/
209
210 - if you want to build with specific options, apply some patches, you'll
211 have to build from sources. If you have little experience or are not
212 certain to devote regular time to perform this task, take an "old" branch
213 (i.e. 1-2 years old max, for example 1.8 when 2.0 is emitted). You'll avoid
214 most bugs and will not have to work too often to update your local version.
215
216 - if you need a fresh version for application development, or to benefit from
217 latest improvements, take the most recent version of the most recent branch
218 and keep it up to date. You may even want to use the Git version or nightly
219 snapshots.
220
221 - if you want to develop on HAProxy, use the master from the Git tree.
222
223 - if you want to follow HAProxy's development by doing some tests without
224 the burden of entering too much into the development process, just use the
225 -dev versions of the master branch. At some point you'll feel the urge to
226 switch to the Git version anyway as it will ultimately simplify your work.
227
228 - if you're installing it on unmanaged servers with little to no hostile
229 exposure, or your home router, you should pick the latest version in one
230 of the oldest supported branches. While it doesn't guarantee that you will
231 never have to upgrade it, at least as long as you don't use too complex a
232 setup, it's unlikely that you will need to update it often.
233
234And as a general rule, do not put a non-LTS version on a server unless you are
235absolutely certain you are going to keep it up to date yourself and already
236plan to replace it once the following LTS version is issued. If you are not
237going to manage updates yourself, use pre-packaged versions exclusively and do
238not expect someone else to have to deal with the burden of building from
239sources.