~bzr-pqm/bzr/bzr.dev : revision 4925

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.