BRANCHES - haproxy - Gitiles

 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, even though 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.
	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, even though 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.