+ <para>
+ The idea of stable and development branches has already been
+ described briefly in <xref linkend="chooseversioning"> and in
+ <xref linkend="delegatebranch">. These alludes attest to the fact
+ to some of the ways that multiple branches can affect your
+ software. Branches can let you avoid (to some extent) some of the
+ problems around rejecting patches (as described in <xref
+ linkend="patching">) by allowing you to temporarily compromise the
+ stability of your project without affected those users who need
+ that stability.
+ </para>
+
+ <para>
+ The most common way of branching your project is to have one
+ branch that is stable and one that is development. This is the
+ model followed by the Linux kernel that is described in <xref
+ linkend="chooseversioning">. In this model, there is always one
+ branch that is stable and always one that is in
+ development. Before any new release, the development branch goes
+ into a <quote>feature freeze</quote> where major changes and added
+ features are rejected or put on hold under the development kernel
+ is released as the new stable branch and major development begins
+ again on the development branch. Bug fixes and small changes that
+ are unlikely to have any large negative repercussions are
+ incorporated into the stable branch also to the development
+ branch.
+ </para>
+
+ <para>
+ Linux's model is an extreme one. On many projects, there is no
+ need to have two versions always available. It may make sense to
+ have two versions only near a release. The Debian project has
+ historically made both a stable and an unstable distribution
+ available but has expanded to this to include: stable, unstable,
+ testing, experimental, and (around release time) a frozen
+ distribution that only incorporates bug fixes during the
+ transition from unstable to stable. There are few projects whose
+ size would necessitate a system like Debian but their use of
+ branches helps demonstrate how they can be used to balance
+ consistent and effective development with the need to make regular
+ and usable releases.
+ </para>
+
+ <para>
+ In trying to set up a development tree for yourself, there are
+ several things that might be useful to keep in mind:
+ </para>
+
+ <para>
+ <variablelist>
+
+ <varlistentry>
+ <term>Minimize the number of branches</term>
+ <listitem>
+ <para>Debian may be able to make good use of four or five
+ branches but it contains gigabytes of software in over 5000
+ packages compiled for a 5-6 different architectures. Two is a
+ good number. Too many branches will confuse your users (I can't
+ count how many times I had to describe Debian's system when it
+ only had 2 and sometimes 3 branches!), potential developers and
+ even yourself. Branches can help but they come at a cost so use
+ them very sparingly.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Make sure that all your different branches are explained</term>
+ <listitem>
+ <para>As I mentioned in the preceding paragraph, different
+ branches <emphasis>will</emphasis> confuse your users. Do
+ everything you can to avoid this by clearly explaining the
+ different branches in a prominent page on your website and in a
+ Readme file in the <acronym>FTP</acronym> or
+ <acronym>HTTP</acronym> directory.</para>
+
+ <para>
+ I might also recommend against a mistake that I think Debian
+ has made. The terms <quote>unstable,</quote>
+ <quote>testing,</quote> and <quote>experimental</quote> are
+ vague and difficult to rank in order of stability (or
+ instability as the case may be). Try explaining to someone
+ that <quote>stable</quote> actually means <quote>ultra
+ stable</quote> and that <quote>unstable</quote> doesn't
+ actually include any unstable software but is really stable
+ software that is untested as a distribution.
+ </para>
+
+ <para>
+ If you are going to do branches, especially early on, keep in
+ mind that people are conditioned to understand the terms
+ <quote>stable</quote> and <quote>development</quote> and you
+ probably can't go wrong with this simple and common division of
+ branches.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Make sure all your branches are always available</term>
+ <listitem>
+ <para>Like a lot of document, this should probably should go
+ without saying but experience has taught me that it's not
+ always obvious to people. It's a good idea to physically split
+ up different branches in different directories or directory
+ trees on your <acronym>FTP</acronym> or <acronym>HTTP</acronym>
+ site. Linux accomplishes this by having all the v2.2 and a v2.3
+ subdirectory where it is immediately obvious (after you know
+ their version numbering scheme) which directory is the most
+ recent stable and the current development releases. Debian
+ accomplishes this by naming all their distribution by name and
+ then changing symlinks named <quote>stable,</quote>
+ <quote>unstable</quote> and <quote>frozen</quote> to point to
+ which ever distribution (by name) is in whatever stage. Both
+ methods work and their are others. In any case, it is important
+ that different branches are always available, are accessible
+ from consistent locations, and that different branches are
+ clearly distinguished from each other so your users know
+ exactly what they want to be downloading and where to get
+ it.</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>