hgbook
changeset 179:5fc4a45c069f
Continue documentation of collaboration models.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Fri Mar 30 23:05:28 2007 -0700 (2007-03-30) |
parents | 1b55292716a4 |
children | 6413f88338df |
files | en/Makefile en/collab.tex en/examples/backout en/examples/backout.manual.merge.out en/examples/backout.non-tip.cat.out en/examples/branching en/examples/branching.clone.out en/examples/branching.init.out en/examples/branching.main.out en/examples/branching.merge.out en/examples/branching.stable.out en/examples/branching.tag.out en/examples/branching.update.out en/feature-branches.dot |
line diff
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 +}