Bazaar

Merge lp:~nmb/bzr/admin-guide-multisite into lp:bzr

  1. admin-guide-multisite
  2. Merge into bzr.dev
Proposed by Neil Martinsen-Burrell
Status: Merged
Approved by: Martin Pool
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
Reviewer Review Type Date Requested Status
Martin Pool Approve
Review via email: mp+15764@code.launchpad.net
To post a comment you must log in.
Revision history for this message
Neil Martinsen-Burrell (nmb) wrote :

This adds a section on multi-site development. It includes one possible way to do such development, but it could use review to see if it is a reasonable suggestion for the Bazaar project to make.

Revision history for this message
Martin Pool (mbp) wrote :

I think this is good but it may be hard to see the big picture. Perhaps a diagram of the various branches and sites would help (but that could be done later.)

+So, we will have three branches stored on two servers:
+trunk-master and trunk-texas at the Texas site and trunk-australia at the
+Darwin site.

I think generally it would cause confusion to have more than one thing called 'trunk', so therefore just one really called 'trunk' and then one integration branch per site.

Even beyond that, it probably makes sense to have an integration branch per logical team not per location, or at least to name them that way if the teams do correspond to the locations.

review: Approve
Revision history for this message
Max Bowsher (maxb) wrote :

Perhaps "Paris, Texas" is not the best example location. I did a double-take reading the example, wondering if a French site was included. Maybe an alternate Texas location that is not also a well-known capital city could be used?

Revision history for this message
Neil Martinsen-Burrell (nmb) wrote :

> Perhaps "Paris, Texas" is not the best example location. I did a double-take
> reading the example, wondering if a French site was included. Maybe an
> alternate Texas location that is not also a well-known capital city could be
> used?

Changed, but I did enjoy the joke for a while :)

Revision history for this message
Neil Martinsen-Burrell (nmb) wrote :

> I think this is good but it may be hard to see the big picture. Perhaps a
> diagram of the various branches and sites would help (but that could be done
> later.)

True, a nice diagram would improve this greatly. We'll see if or when I get a chance to draw it.

> +So, we will have three branches stored on two servers:
> +trunk-master and trunk-texas at the Texas site and trunk-australia at the
> +Darwin site.
>
> I think generally it would cause confusion to have more than one thing called
> 'trunk', so therefore just one really called 'trunk' and then one integration
> branch per site.

Changed in the branch.

> Even beyond that, it probably makes sense to have an integration branch per
> logical team not per location, or at least to name them that way if the teams
> do correspond to the locations.

Clarified in the branch.

Revision history for this message
Martin Pool (mbp) wrote :

2009/12/22 Neil Martinsen-Burrell <email address hidden>:
>> Perhaps "Paris, Texas" is not the best example location. I did a double-take
>> reading the example, wondering if a French site was included. Maybe an
>> alternate Texas location that is not also a well-known capital city could be
>> used?
>
> Changed, but I did enjoy the joke for a while :)

Also, it's too hot to think in Darwin ;-)

--
Martin <http://launchpad.net/~mbp/>

Revision history for this message
Neil Martinsen-Burrell (nmb) wrote :

On 2009-12-21 23:48 , Martin Pool wrote:
> 2009/12/22 Neil Martinsen-Burrell<email address hidden>:
>>> Perhaps "Paris, Texas" is not the best example location. I did a double-take
>>> reading the example, wondering if a French site was included. Maybe an
>>> alternate Texas location that is not also a well-known capital city could be
>>> used?
>>
>> Changed, but I did enjoy the joke for a while :)
>
> Also, it's too hot to think in Darwin ;-)

Exactly. I'm not changing that one.

Preview Diff

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