1.1 --- a/en/collab.tex	Thu Mar 22 23:03:11 2007 -0700
     1.2 +++ b/en/collab.tex	Fri Mar 30 23:05:28 2007 -0700
     1.3 @@ -74,7 +74,7 @@
     1.4  
     1.5  \subsection{A single central repository}
     1.6  
     1.7 -For smaller projects, migrating from a centralised revision control
     1.8 +For smaller projects migrating from a centralised revision control
     1.9  tool, perhaps the easiest way to get started is to have changes flow
    1.10  through a single shared central repository.  This is also the
    1.11  most common ``building block'' for more ambitious workflow schemes.
    1.12 @@ -84,7 +84,7 @@
    1.13  developers have permission to push a change back when they're ready
    1.14  for other people to see it.
    1.15  
    1.16 -Under this model, it can still sometimes make sense for people to pull
    1.17 +Under this model, it can still often make sense for people to pull
    1.18  changes directly from each other, without going through the central
    1.19  repository.  Consider a case in which I have a tentative bug fix, but
    1.20  I am worried that if I were to publish it to the central repository,
    1.21 @@ -102,6 +102,97 @@
    1.22  needs of people who don't have push access, and those who want to use
    1.23  web browsers to browse the repository's history.
    1.24  
    1.25 +\subsection{Working with multiple branches}
    1.26 +
    1.27 +Projects of any significant size naturally tend to make progress on
    1.28 +several fronts simultaneously.  In the case of software, it's common
    1.29 +for a project to go through periodic official releases.  A release
    1.30 +might then go into ``maintenance mode'' for a while after its first
    1.31 +publication; maintenance releases tend to contain only bug fixes, not
    1.32 +new features.  In parallel with these maintenance releases, one or
    1.33 +more future releases may be under development.  People normally use
    1.34 +the word ``branch'' to refer to one of these many slightly different
    1.35 +directions in which development is proceeding.
    1.36 +
    1.37 +Mercurial is particularly well suited to managing a number of
    1.38 +simultaneous, but not identical, branches.  Each ``development
    1.39 +direction'' can live in its own central repository, and you can merge
    1.40 +changes from one to another as the need arises.  Because repositories
    1.41 +are independent of each other, unstable changes in a development
    1.42 +branch will never affect a stable branch unless someone explicitly
    1.43 +merges those changes in.
    1.44 +
    1.45 +Here's an example of how this can work in practice.  Let's say you
    1.46 +have one ``main branch'' on a central server.
    1.47 +\interaction{branching.init}
    1.48 +People clone it, make changes locally, test them, and push them back.
    1.49 +
    1.50 +Once the main branch reaches a release milestone, you can use the
    1.51 +\hgcmd{tag} command to give a permanent name to the milestone
    1.52 +revision.
    1.53 +\interaction{branching.tag}
    1.54 +Let's say some ongoing development occurs on the main branch.
    1.55 +\interaction{branching.main}
    1.56 +Using the tag that was recorded at the milestone, people who clone
    1.57 +that repository at any time in the future can use \hgcmd{update} to
    1.58 +get a copy of the working directory exactly as it was when that tagged
    1.59 +revision was committed.  
    1.60 +\interaction{branching.update}
    1.61 +
    1.62 +In addition, immediately after the main branch is tagged, someone can
    1.63 +then clone the main branch on the server to a new ``stable'' branch,
    1.64 +also on the server.
    1.65 +\interaction{branching.clone}
    1.66 +
    1.67 +Someone who needs to make a change to the stable branch can then clone
    1.68 +\emph{that} repository, make their changes, commit, and push their
    1.69 +changes back there.
    1.70 +\interaction{branching.stable}
    1.71 +Because Mercurial repositories are independent, and Mercurial doesn't
    1.72 +move changes around automatically, the stable and main branches are
    1.73 +\emph{isolated} from each other.  The changes that you made on the
    1.74 +main branch don't ``leak'' to the stable branch, and vice versa.
    1.75 +
    1.76 +You'll often want all of your bugfixes on the stable branch to show up
    1.77 +on the main branch, too.  Rather than rewrite a bugfix on the main
    1.78 +branch, you can simply pull and merge changes from the stable to the
    1.79 +main branch, and Mercurial will bring those bugfixes in for you.
    1.80 +\interaction{branching.merge}
    1.81 +The main branch will still contain changes that are not on the stable
    1.82 +branch, but it will also contain all of the bugfixes from the stable
    1.83 +branch.  The stable branch remains unaffected by these changes.
    1.84 +
    1.85 +\subsection{Feature branches}
    1.86 +
    1.87 +For larger projects, an effective way to manage change is to break up
    1.88 +a team into smaller groups.  Each group has a shared branch of its
    1.89 +own, cloned from a single ``master'' branch used by the entire
    1.90 +project.  People working on an individual branch are typically quite
    1.91 +isolated from developments on other branches.
    1.92 +
    1.93 +\begin{figure}[ht]
    1.94 +  \centering
    1.95 +  \grafix{feature-branches}
    1.96 +  \caption{Feature branches}
    1.97 +  \label{fig:collab:feature-branches}
    1.98 +\end{figure}
    1.99 +
   1.100 +When a particular feature is deemed to be in suitable shape, someone
   1.101 +on that feature team pulls and merges from the master branch into the
   1.102 +feature branch, then pushes back up to the master branch.
   1.103 +
   1.104 +\subsection{The release train}
   1.105 +
   1.106 +Some projects are organised on a ``train'' basis: a release is
   1.107 +scheduled to happen every few months, and whatever features are ready
   1.108 +when the ``train'' is ready to leave are allowed in.
   1.109 +
   1.110 +This model resembles working with feature branches.  The difference is
   1.111 +that when a feature branch misses a train, someone on the feature team
   1.112 +pulls and merges the changes that went out on that train release, and
   1.113 +the team continues its work on top of that release so that their
   1.114 +feature can make the next release.
   1.115 +
   1.116  \subsection{The Linux kernel model}
   1.117  
   1.118  The development of the Linux kernel has a shallow hierarchical