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