← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/admin-guide/advanced.txt

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2010-03-11 13:47:06 UTC
  • mfrom: (5051.3.16 use-branch-open)
  • Revision ID: pqm@pqm.ubuntu.com-20100311134706-kaerqhx3lf7xn6rh
(Jelmer) Pass colocated branch names further down the call stack.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/admin-guide/advanced.txt
 
1
Advanced Topics
 
2
===============
 
3
 
 
4
System Monitoring
 
5
-----------------
 
6
 
 
7
Capacity Planning Tips
 
8
----------------------
 
9
 
 
10
Clustering
 
11
----------
 
12
 
 
13
Multi-site Setups
 
14
-----------------
 
15
 
 
16
The "distributed" in distributed version control system should indicate that
 
17
Bazaar is  well suited for multi-site development situations and indeed, that
 
18
is the case.  The advantage comes from the ease and transparency of managing
 
19
merges between branches with divergent history.  Note that there are many,
 
20
many different ways to manage widely-flung development setups using Bazaar and
 
21
its branching and merging capabilities.  These can be discovered and tested
 
22
before being implemented as policy.  We will describe one such possible setup
 
23
here.
 
24
 
 
25
Consider ProjectX Corp's international expansion with a new branch office in
 
26
Darwin, Australia, in addition to the company's headquarters in Austin, Texas,
 
27
USA.  One of the difficulties of a far-flung multi-site development
 
28
environment such as this is that the network connection between Australia and
 
29
Texas is slow and unreliable.  So, each branch office would like the master
 
30
branch to be local to them.  (In situations with good network connectivity, a
 
31
local branch bound to the remote master may be all that is needed to support
 
32
multi-site development.)
 
33
 
 
34
Of course, with two master branches, there is always the question of which one
 
35
is authoritative.  Given Bazaar's facility at managing multiple branches, we
 
36
suggest that it is best not to privilege either the Texas or Australia
 
37
branches, but to merge both of them into a separate master branch (which may
 
38
reside at either site).  For definiteness, we will locate the master branch at
 
39
the Texas site.  So, we will have three branches stored on two servers:
 
40
trunk and texas-integration at the Texas site and australia-integration at the
 
41
Darwin site.  These branches are named in terms of the sites where the 
 
42
development takes place, but in many cases it may make more sense to name
 
43
branches after the functional teams rather their geographical locations.
 
44
Since we are trying illustrate the issues with multi-*site* development, we
 
45
will persist in this naming scheme.
 
46
 
 
47
Setup
 
48
~~~~~
 
49
 
 
50
Using our previous setup at the Texas site, we will simply rename the old
 
51
trunk branch as trunk and branch a copy as texas-integration.
 
52
 
 
53
::
 
54
 
 
55
  $ cd /srv/bzr/projectx
 
56
  $ mv trunk trunk              # can simply rename on the filesystem
 
57
  $ bzr branch trunk texas-integration   # very fast in a shared repository
 
58
 
 
59
In Australia, we need to set up the ``/srv/bzr/projectx`` directory and get a
 
60
copy of the current trunk as australia-integration::
 
61
 
 
62
  $ mkdir -p /srv/bzr
 
63
  $ cd /srv/bzr
 
64
  $ bzr init-repo --no-trees projectx
 
65
  $ cd projectx
 
66
  $ bzr branch bzr+ssh://server.example.com/srv/bzr/trunk
 
67
  $ bzr branch trunk australia-integration
 
68
 
 
69
Merging to master
 
70
~~~~~~~~~~~~~~~~~
 
71
 
 
72
Then, each office works with their local copy of the trunk.  At some point,
 
73
sooner or later depending on the pace of development in the two locations, the
 
74
two local trunks need to be merged.  (In general, sooner beats later when
 
75
merging, since there is no penalty for multiple merges.)  In this example,
 
76
Alice at the Texas office will do the merging on her local machine using
 
77
branches on the server::
 
78
 
 
79
  # Get a copy of the Australia branch in Texas.  After the initial branch
 
80
  # command, use pull to keep the branch up to date.  With a slow network,
 
81
  # this is the only slow part
 
82
  $ bzr branch bzr+ssh://autralia.example.com/srv/bzr/projectx/australia-integration \
 
83
    bzr+ssh://server.example.com/srv/bzr/projectx/australia-integration
 
84
  
 
85
  # Check out the master branch locally for doing the merge
 
86
  $ cd ~/projectx
 
87
  $ bzr checkout bzr+ssh://server.example.com/srv/bzr/projectx/trunk
 
88
  $ cd trunk
 
89
  $ bzr merge bzr+ssh://server.example.com/srv/bzr/projectx/texas-integration
 
90
  # Run the test suite and resolve any conflicts
 
91
  $ bzr commit -m "Merge Texas branch to master"
 
92
  
 
93
  # Now, merge from Australia using the local copy of that branch
 
94
  $ bzr merge bzr+ssh://server.example.com/srv/bzr/projectx/australia-integration
 
95
  # Run the test suite and resolve any conflicts between the two offices
 
96
  $ bzr commit -m "Merge Australia branch to master"
 
97
 
 
98
Note that Bazaar does not commit even cleanly applied merges by default.  This
 
99
is because although a merge may apply cleanly, the merged state still needs to
 
100
be checked before it is committed.  (Just because there are no text conflicts
 
101
does not mean that everything will work after a merge.)  An alternative that 
 
102
can pull when possible and merge otherwise is available with 
 
103
``bzr merge --pull``.
 
104
 
 
105
Merging back to local trunks
 
106
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
107
 
 
108
Now the trunk branch is the most up-to-date version of the software and
 
109
both of the local trunks need to reincorporate the changes from the master.
 
110
If no new commits have been made to texas-integration, then that can happen using
 
111
``bzr pull``::
 
112
 
 
113
  $ cd ~/projectx
 
114
  $ bzr checkout bzr+ssh://server.example.com/srv/bzr/projectx/texas-integration
 
115
  $ cd texas-integration
 
116
  $ bzr pull ../trunk  # Use trunk from the local disk
 
117
                              # No need to commit
 
118
 
 
119
If new changes have happened on texas-integration since the integration with
 
120
trunk, then the above pull will produce an error suggesting to use
 
121
merge::
 
122
 
 
123
  $ bzr merge ../trunk
 
124
  # Run test suite, resolve conflicts
 
125
  $ bzr commit -m "Merging Australian changes"
 
126
 
 
127
In Australia, they will need to update their local copy of trunk::
 
128
 
 
129
  $ cd /srv/bzr/projectx/trunk
 
130
  $ bzr pull     # parent location is used by default
 
131
 
 
132
Then, they need to pull or merge the changes from trunk into the local trunk.
 
133
This should be done by a developer with a checkout of australia-integration so
 
134
that they can run the test suite::
 
135
 
 
136
  $ cd ~/projectx
 
137
  $ bzr co bzr+ssh://australia.example.com/srv/bzr/projectx/australia-integration
 
138
  $ cd australia-integration
 
139
  $ bzr merge bzr+ssh://australia.example.com/srv/bzr/projectx/trunk
 
140
  # Run test suite and integrate Texan changes with only recent local
 
141
  # development
 
142
  $ bzr commit -m "Integrate work from Texas"
 
143
 
 
144
 
 
145
Other Considerations
 
146
~~~~~~~~~~~~~~~~~~~~
 
147
 
 
148
Multi-site deployments can be complicated, due to the many possible variations
 
149
of development velocity, divisions of labor, network connectivity, resources
 
150
for integration, etc.  The preceding description is meant to be one possible
 
151
way to do fairly symmetric multi-site development.  (Neither Texas or
 
152
Australia is privileged in this structure.)  In a situation where there is one
 
153
main site and other smaller sites, one of the local trunk branches can be
 
154
eliminated and trunk can be used directly for development at the main
 
155
site.
 
156
 
 
157
It is also up to the particular situation how frequently the local trunks are
 
158
integrated into the master trunk.  Given resources specifically for
 
159
integration, it is conceivable that a developer may be constantly responsible
 
160
for integrating changes from the two teams.  Alternatively, the two sites
 
161
could work on well-separated, well-defined features and merge to the master
 
162
trunk only when their respective features are complete.  Given the difficulty
 
163
of resolving conflicts in very large merges and the ease of merge handling in
 
164
Bazaar, we suggest that merges be done more frequently, rather than less.