1.1 --- a/en/branch.tex	Mon Apr 16 16:33:51 2007 -0700
     1.2 +++ b/en/branch.tex	Mon Apr 16 17:21:38 2007 -0700
     1.3 @@ -126,6 +126,24 @@
     1.4  which you can then fix and commit.  You should then run \hgcmd{tags}
     1.5  again, just to be sure that your fix is correct.
     1.6  
     1.7 +\subsection{Tags and cloning}
     1.8 +
     1.9 +You may have noticed that the \hgcmd{clone} command has a
    1.10 +\hgopt{clone}{-r} option that lets you clone an exact copy of
    1.11 +repository as of a particular changeset.  The new clone will not
    1.12 +contain any project history that comes after the revision you
    1.13 +specified.  This has an interaction with tags that can surprise the
    1.14 +unwary.
    1.15 +
    1.16 +Recall that a tag is stored as a revision to the \sfilename{.hgtags}
    1.17 +file, so that when you create a tag, the changeset in which it's
    1.18 +recorded necessarily refers to an older changeset.  When you run
    1.19 +\hgcmdargs{clone}{-r foo} to clone a repository as of tag
    1.20 +\texttt{foo}, the new clone \emph{will not contain the history that
    1.21 +  created the tag} that you used to clone the repository.  The result
    1.22 +is that you'll get exactly the right subset of the project's history
    1.23 +in the new repository, but \emph{not} the tag you might have expected.
    1.24 +
    1.25  \subsection{When permanent tags are too much}
    1.26  
    1.27  Since Mercurial's tags are revision controlled and carried around with
    1.28 @@ -144,6 +162,53 @@
    1.29  create using \hgopt{tag}{-l} remain strictly local to the repository
    1.30  you're currently working in.
    1.31  
    1.32 +\section{The flow of changes---big picture vs. little}
    1.33 +
    1.34 +To return to the outline I sketched at the beginning of a chapter,
    1.35 +let's think about a project that has multiple concurrent pieces of
    1.36 +work under development at once.
    1.37 +
    1.38 +There might be a push for a new ``main'' release; a new minor bugfix
    1.39 +release to the last main release; and an unexpected ``hot fix'' to an
    1.40 +old release that is now in maintenance mode.
    1.41 +
    1.42 +The usual way people refer to these different concurrent directions of
    1.43 +development is as ``branches''.  However, we've already seen numerous
    1.44 +times that Mercurial treats \emph{all of history} as a series of
    1.45 +branches and merges.  Really, what we have here is two ideas that are
    1.46 +peripherally related, but which happen to share a name.
    1.47 +\begin{itemize}
    1.48 +\item ``Big picture'' branches represent the sweep of a project's
    1.49 +  evolution; people give them names, and talk about them in
    1.50 +  conversation.
    1.51 +\item ``Little picture'' branches are artefacts of the day-to-day
    1.52 +  activity of developing and merging changes.  They expose the
    1.53 +  narrative of how the code was developed.
    1.54 +\end{itemize}
    1.55 +
    1.56 +\section{Managing big-picture branches in repositories}
    1.57 +
    1.58 +The easiest way to isolate a ``big picture'' branch in Mercurial is in
    1.59 +a dedicated repository.  If you have an existing shared
    1.60 +repository---let's call it \texttt{myproject}---that reaches a ``1.0''
    1.61 +milestone, you can start to prepare for future maintenance releases on
    1.62 +top of version~1.0 by tagging the revision from which you prepared
    1.63 +the~1.0 release.
    1.64 +\interaction{branch-repo.tag}
    1.65 +You can then clone a new shared \texttt{myproject-1.0.1} repository as
    1.66 +of that tag.
    1.67 +\interaction{branch-repo.clone}
    1.68 +
    1.69 +Afterwards, if someone needs to work on a bug fix that ought to go
    1.70 +into an upcoming~1.0.1 minor release, they clone the
    1.71 +\texttt{myproject-1.0.1} repository, make their changes, and push them
    1.72 +back.
    1.73 +\interaction{branch-repo.bugfix}
    1.74 +Meanwhile, development for the next major release can continue,
    1.75 +isolated and unabated, in the \texttt{myproject} repository.
    1.76 +\interaction{branch-repo.new}
    1.77 +
    1.78 +
    1.79  
    1.80  %%% Local Variables: 
    1.81  %%% mode: latex