1.1 --- a/en/Makefile	Thu Mar 29 19:55:18 2007 +0100
     1.2 +++ b/en/Makefile	Fri Mar 30 23:05:28 2007 -0700
     1.3 @@ -24,6 +24,7 @@
     1.4  	undo.tex
     1.5  
     1.6  image-sources := \
     1.7 +	feature-branches.dot \
     1.8  	filelog.svg \
     1.9  	kdiff3.png \
    1.10  	metadata.svg \
    1.11 @@ -53,6 +54,7 @@
    1.12  example-sources := \
    1.13  	backout \
    1.14  	bisect \
    1.15 +	branching \
    1.16  	cmdref \
    1.17  	daily.copy \
    1.18  	daily.files \

     2.1 --- a/en/collab.tex	Thu Mar 29 19:55:18 2007 +0100
     2.2 +++ b/en/collab.tex	Fri Mar 30 23:05:28 2007 -0700
     2.3 @@ -74,7 +74,7 @@
     2.4  
     2.5  \subsection{A single central repository}
     2.6  
     2.7 -For smaller projects, migrating from a centralised revision control
     2.8 +For smaller projects migrating from a centralised revision control
     2.9  tool, perhaps the easiest way to get started is to have changes flow
    2.10  through a single shared central repository.  This is also the
    2.11  most common ``building block'' for more ambitious workflow schemes.
    2.12 @@ -84,7 +84,7 @@
    2.13  developers have permission to push a change back when they're ready
    2.14  for other people to see it.
    2.15  
    2.16 -Under this model, it can still sometimes make sense for people to pull
    2.17 +Under this model, it can still often make sense for people to pull
    2.18  changes directly from each other, without going through the central
    2.19  repository.  Consider a case in which I have a tentative bug fix, but
    2.20  I am worried that if I were to publish it to the central repository,
    2.21 @@ -102,6 +102,97 @@
    2.22  needs of people who don't have push access, and those who want to use
    2.23  web browsers to browse the repository's history.
    2.24  
    2.25 +\subsection{Working with multiple branches}
    2.26 +
    2.27 +Projects of any significant size naturally tend to make progress on
    2.28 +several fronts simultaneously.  In the case of software, it's common
    2.29 +for a project to go through periodic official releases.  A release
    2.30 +might then go into ``maintenance mode'' for a while after its first
    2.31 +publication; maintenance releases tend to contain only bug fixes, not
    2.32 +new features.  In parallel with these maintenance releases, one or
    2.33 +more future releases may be under development.  People normally use
    2.34 +the word ``branch'' to refer to one of these many slightly different
    2.35 +directions in which development is proceeding.
    2.36 +
    2.37 +Mercurial is particularly well suited to managing a number of
    2.38 +simultaneous, but not identical, branches.  Each ``development
    2.39 +direction'' can live in its own central repository, and you can merge
    2.40 +changes from one to another as the need arises.  Because repositories
    2.41 +are independent of each other, unstable changes in a development
    2.42 +branch will never affect a stable branch unless someone explicitly
    2.43 +merges those changes in.
    2.44 +
    2.45 +Here's an example of how this can work in practice.  Let's say you
    2.46 +have one ``main branch'' on a central server.
    2.47 +\interaction{branching.init}
    2.48 +People clone it, make changes locally, test them, and push them back.
    2.49 +
    2.50 +Once the main branch reaches a release milestone, you can use the
    2.51 +\hgcmd{tag} command to give a permanent name to the milestone
    2.52 +revision.
    2.53 +\interaction{branching.tag}
    2.54 +Let's say some ongoing development occurs on the main branch.
    2.55 +\interaction{branching.main}
    2.56 +Using the tag that was recorded at the milestone, people who clone
    2.57 +that repository at any time in the future can use \hgcmd{update} to
    2.58 +get a copy of the working directory exactly as it was when that tagged
    2.59 +revision was committed.  
    2.60 +\interaction{branching.update}
    2.61 +
    2.62 +In addition, immediately after the main branch is tagged, someone can
    2.63 +then clone the main branch on the server to a new ``stable'' branch,
    2.64 +also on the server.
    2.65 +\interaction{branching.clone}
    2.66 +
    2.67 +Someone who needs to make a change to the stable branch can then clone
    2.68 +\emph{that} repository, make their changes, commit, and push their
    2.69 +changes back there.
    2.70 +\interaction{branching.stable}
    2.71 +Because Mercurial repositories are independent, and Mercurial doesn't
    2.72 +move changes around automatically, the stable and main branches are
    2.73 +\emph{isolated} from each other.  The changes that you made on the
    2.74 +main branch don't ``leak'' to the stable branch, and vice versa.
    2.75 +
    2.76 +You'll often want all of your bugfixes on the stable branch to show up
    2.77 +on the main branch, too.  Rather than rewrite a bugfix on the main
    2.78 +branch, you can simply pull and merge changes from the stable to the
    2.79 +main branch, and Mercurial will bring those bugfixes in for you.
    2.80 +\interaction{branching.merge}
    2.81 +The main branch will still contain changes that are not on the stable
    2.82 +branch, but it will also contain all of the bugfixes from the stable
    2.83 +branch.  The stable branch remains unaffected by these changes.
    2.84 +
    2.85 +\subsection{Feature branches}
    2.86 +
    2.87 +For larger projects, an effective way to manage change is to break up
    2.88 +a team into smaller groups.  Each group has a shared branch of its
    2.89 +own, cloned from a single ``master'' branch used by the entire
    2.90 +project.  People working on an individual branch are typically quite
    2.91 +isolated from developments on other branches.
    2.92 +
    2.93 +\begin{figure}[ht]
    2.94 +  \centering
    2.95 +  \grafix{feature-branches}
    2.96 +  \caption{Feature branches}
    2.97 +  \label{fig:collab:feature-branches}
    2.98 +\end{figure}
    2.99 +
   2.100 +When a particular feature is deemed to be in suitable shape, someone
   2.101 +on that feature team pulls and merges from the master branch into the
   2.102 +feature branch, then pushes back up to the master branch.
   2.103 +
   2.104 +\subsection{The release train}
   2.105 +
   2.106 +Some projects are organised on a ``train'' basis: a release is
   2.107 +scheduled to happen every few months, and whatever features are ready
   2.108 +when the ``train'' is ready to leave are allowed in.
   2.109 +
   2.110 +This model resembles working with feature branches.  The difference is
   2.111 +that when a feature branch misses a train, someone on the feature team
   2.112 +pulls and merges the changes that went out on that train release, and
   2.113 +the team continues its work on top of that release so that their
   2.114 +feature can make the next release.
   2.115 +
   2.116  \subsection{The Linux kernel model}
   2.117  
   2.118  The development of the Linux kernel has a shallow hierarchical

     3.1 --- a/en/examples/backout	Thu Mar 29 19:55:18 2007 +0100
     3.2 +++ b/en/examples/backout	Fri Mar 30 23:05:28 2007 -0700
     3.3 @@ -6,7 +6,7 @@
     3.4  export HGMERGE=$(mktemp)
     3.5  echo '#!/bin/sh' >> $HGMERGE
     3.6  echo 'echo first change > "$1"' >> $HGMERGE
     3.7 -echo 'echo third change > "$1"' >> $HGMERGE
     3.8 +echo 'echo third change >> "$1"' >> $HGMERGE
     3.9  chmod 700 $HGMERGE
    3.10  
    3.11  #$ name: init

     4.1 --- a/en/examples/backout.manual.merge.out	Thu Mar 29 19:55:18 2007 +0100
     4.2 +++ b/en/examples/backout.manual.merge.out	Fri Mar 30 23:05:28 2007 -0700
     4.3 @@ -4,4 +4,5 @@
     4.4  (branch merge, don't forget to commit)
     4.5  $ \textbf{hg commit -m 'merged backout with previous tip'}
     4.6  $ \textbf{cat myfile}
     4.7 +first change
     4.8  third change

     5.1 --- a/en/examples/backout.non-tip.cat.out	Thu Mar 29 19:55:18 2007 +0100
     5.2 +++ b/en/examples/backout.non-tip.cat.out	Fri Mar 30 23:05:28 2007 -0700
     5.3 @@ -1,2 +1,3 @@
     5.4  $ \textbf{cat myfile}
     5.5 +first change
     5.6  third change

     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/en/examples/branching	Fri Mar 30 23:05:28 2007 -0700
     6.3 @@ -0,0 +1,62 @@
     6.4 +#!/bin/bash
     6.5 +
     6.6 +#$ name: init
     6.7 +
     6.8 +hg init main
     6.9 +cd main
    6.10 +echo 'This is a boring feature.' > myfile
    6.11 +hg commit -A -m 'We have reached an important milestone!'
    6.12 +
    6.13 +#$ name: tag
    6.14 +
    6.15 +hg tag v1.0
    6.16 +hg tip
    6.17 +hg tags
    6.18 +
    6.19 +#$ name: main
    6.20 +
    6.21 +cd ../main
    6.22 +echo 'This is exciting and new!' >> myfile
    6.23 +hg commit -m 'Add a new feature'
    6.24 +cat myfile
    6.25 +
    6.26 +#$ name: update
    6.27 +
    6.28 +cd ..
    6.29 +hg clone -U main main-old
    6.30 +cd main-old
    6.31 +hg update v1.0
    6.32 +cat myfile
    6.33 +
    6.34 +#$ name: clone
    6.35 +
    6.36 +cd ..
    6.37 +hg clone -rv1.0 main stable
    6.38 +
    6.39 +#$ name: stable
    6.40 +
    6.41 +hg clone stable stable-fix
    6.42 +cd stable-fix
    6.43 +echo 'This is a fix to a boring feature.' > myfile
    6.44 +hg commit -m 'Fix a bug'
    6.45 +hg push
    6.46 +
    6.47 +#$ name:
    6.48 +
    6.49 +export HGMERGE=$(mktemp)
    6.50 +echo '#!/bin/sh' > $HGMERGE
    6.51 +echo 'echo "This is a fix to a boring feature." > "$1"' >> $HGMERGE
    6.52 +echo 'echo "This is exciting and new!" >> "$1"' >> $HGMERGE
    6.53 +chmod 700 $HGMERGE
    6.54 +
    6.55 +#$ name: merge
    6.56 +
    6.57 +cd ../main
    6.58 +hg pull ../stable
    6.59 +hg merge
    6.60 +hg commit -m 'Bring in bugfix from stable branch'
    6.61 +cat myfile
    6.62 +
    6.63 +#$ name:
    6.64 +
    6.65 +rm $HGMERGE

     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/en/examples/branching.clone.out	Fri Mar 30 23:05:28 2007 -0700
     7.3 @@ -0,0 +1,8 @@
     7.4 +$ \textbf{cd ..}
     7.5 +$ \textbf{hg clone -rv1.0 main stable}
     7.6 +requesting all changes
     7.7 +adding changesets
     7.8 +adding manifests
     7.9 +adding file changes
    7.10 +added 1 changesets with 1 changes to 1 files
    7.11 +1 files updated, 0 files merged, 0 files removed, 0 files unresolved

     8.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     8.2 +++ b/en/examples/branching.init.out	Fri Mar 30 23:05:28 2007 -0700
     8.3 @@ -0,0 +1,5 @@
     8.4 +$ \textbf{hg init main}
     8.5 +$ \textbf{cd main}
     8.6 +$ \textbf{echo 'This is a boring feature.' > myfile}
     8.7 +$ \textbf{hg commit -A -m 'We have reached an important milestone!'}
     8.8 +adding myfile

     9.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     9.2 +++ b/en/examples/branching.main.out	Fri Mar 30 23:05:28 2007 -0700
     9.3 @@ -0,0 +1,6 @@
     9.4 +$ \textbf{cd ../main}
     9.5 +$ \textbf{echo 'This is exciting and new!' >> myfile}
     9.6 +$ \textbf{hg commit -m 'Add a new feature'}
     9.7 +$ \textbf{cat myfile}
     9.8 +This is a boring feature.
     9.9 +This is exciting and new!

    10.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    10.2 +++ b/en/examples/branching.merge.out	Fri Mar 30 23:05:28 2007 -0700
    10.3 @@ -0,0 +1,17 @@
    10.4 +$ \textbf{cd ../main}
    10.5 +$ \textbf{hg pull ../stable}
    10.6 +pulling from ../stable
    10.7 +searching for changes
    10.8 +adding changesets
    10.9 +adding manifests
   10.10 +adding file changes
   10.11 +added 1 changesets with 1 changes to 1 files (+1 heads)
   10.12 +(run 'hg heads' to see heads, 'hg merge' to merge)
   10.13 +$ \textbf{hg merge}
   10.14 +merging myfile
   10.15 +0 files updated, 1 files merged, 0 files removed, 0 files unresolved
   10.16 +(branch merge, don't forget to commit)
   10.17 +$ \textbf{hg commit -m 'Bring in bugfix from stable branch'}
   10.18 +$ \textbf{cat myfile}
   10.19 +This is a fix to a boring feature.
   10.20 +This is exciting and new!

    11.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    11.2 +++ b/en/examples/branching.stable.out	Fri Mar 30 23:05:28 2007 -0700
    11.3 @@ -0,0 +1,12 @@
    11.4 +$ \textbf{hg clone stable stable-fix}
    11.5 +1 files updated, 0 files merged, 0 files removed, 0 files unresolved
    11.6 +$ \textbf{cd stable-fix}
    11.7 +$ \textbf{echo 'This is a fix to a boring feature.' > myfile}
    11.8 +$ \textbf{hg commit -m 'Fix a bug'}
    11.9 +$ \textbf{hg push}
   11.10 +pushing to /tmp/branchingfJgZac/stable
   11.11 +searching for changes
   11.12 +adding changesets
   11.13 +adding manifests
   11.14 +adding file changes
   11.15 +added 1 changesets with 1 changes to 1 files

    12.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    12.2 +++ b/en/examples/branching.tag.out	Fri Mar 30 23:05:28 2007 -0700
    12.3 @@ -0,0 +1,11 @@
    12.4 +$ \textbf{hg tag v1.0}
    12.5 +$ \textbf{hg tip}
    12.6 +changeset:   
    12.7 +tag:         tip
    12.8 +user:        Bryan O'Sullivan <bos@serpentine.com>
    12.9 +
   12.10 +summary:     Added tag v1.0 for changeset 
   12.11 +
   12.12 +$ \textbf{hg tags}
   12.13 +tip                                
   12.14 +v1.0                               

    13.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    13.2 +++ b/en/examples/branching.update.out	Fri Mar 30 23:05:28 2007 -0700
    13.3 @@ -0,0 +1,7 @@
    13.4 +$ \textbf{cd ..}
    13.5 +$ \textbf{hg clone -U main main-old}
    13.6 +$ \textbf{cd main-old}
    13.7 +$ \textbf{hg update v1.0}
    13.8 +1 files updated, 0 files merged, 0 files removed, 0 files unresolved
    13.9 +$ \textbf{cat myfile}
   13.10 +This is a boring feature.

    14.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    14.2 +++ b/en/feature-branches.dot	Fri Mar 30 23:05:28 2007 -0700
    14.3 @@ -0,0 +1,8 @@
    14.4 +digraph feature_branches {
    14.5 +	master -> crypto;
    14.6 +	master -> filesystems;
    14.7 +	master -> ipc;
    14.8 +	master -> memory;
    14.9 +	master -> network;
   14.10 +	master -> security;
   14.11 +}