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

1

====================

2

Centralized Workflow

3

====================

4

5

Overview

6

========

7

8

This document describes some basic workflow for using Bazaar_. This doesn't

9

try to explain *why* every step is done, but more gives recommendations

10

about what is considered a good way to work with Bazaar_.

11

Bazaar_ is designed to be very flexible in workflows, from fully

12

decentralized to mostly centralized.

13

The practices here are meant to help ease the user into more advanced usage

14

of Bazaar_, and allowing them to work in a mix of centralized and

15

decentralized operation.

16

17

In general, this document is meant for people in a work setting. Where

18

several people are working on the same codebase, and want to work with

19

eachother and keep in sync. However, this workflow is also applicable to a

20

single developer, who might work on several machines, and wants to keep in

21

sync with themselves.

22

23

.. _Bazaar: http://bazaar-vcs.org

24

25

26

Initial Setup

27

=============

28

29

These are some reasonably simple steps to setup Bazaar_ so that it works

30

well for you.

31

32

33

Setting User Email

34

------------------

35

36

Your user identity is stored with each commit. While this doesn't have to

37

be accurate, unique, or anything else, it will be used in log messages an

38

annotations, so it is nice to have something real.::

39

40

% bzr whoami "John Doe <jdoe@organization.com>"

41

42

43

Setting up a local Repository

44

-----------------------------

45

46

Bazaar_ branches generally copy the history information around with them,

47

which is part of how you can work in a fully decentralized manner. As an

48

optimization, it is possible for branches to combine their storage needs,

49

so that you do not need to copy around all of this history information

50

whenever you create a new branch.

51

52

The best way to do this is to create a `Shared Repository`_. In general,

53

branches will share their storage if they exist in a subdirectory of a

54

`Shared Repository`_. So lets setup a `Shared Repository`_ in our home

55

directory, thus all branches we create underneath will share their history

56

storage.::

57

58

% bzr init-repo --trees ~

59

60

61

Setting up a remote Repository

62

------------------------------

63

64

Many times you want a location where data is stored separate from where

65

you do your work. This workflow is required by centralized systems (CVS/SVN).

66

Usually they are on separate machines, but not always. This is actually a

67

pretty good setup, especially in a work environment. Because it ensures

68

a central location where data can be backed up, and means that if something

69

happens to a developer's machine, no committed work has been lost.

70

71

So lets set up a shared location for our project. Again, we will use a

72

`Shared Repository`_ to optimize disk usage.::

73

74

% bzr init-repo --no-trees sftp://centralhost/srv/bzr/

75

76

You can think of this step as similar to setting up a new cvsroot, or

77

subversion repository (only obviously it is a little bit simpler).

78

79

80

Starting to version an existing project

81

=======================================

82

83

Now that we have a repository, lets get going with a new project. Most of

84

the time, you will already have some code that you started working with,

85

that you now want to version using Bazaar_. If the code was originally

86

in source control, there are many ways to convert the project to Bazaar_

87

without losing any history. However, this is outside of the scope of this

88

document. See XXXReferenceConversionOfHistory_.

89

90

91

Developer 1: Creating the first revision

92

----------------------------------------

93

94

So first, we want to create a branch in our remote Repository, where we

95

will want to host the project. Let's assume we have a project named

96

"sigil" that we want to start versioning, and create an empty branch::

97

98

% bzr init sftp://centralhost/srv/bzr/sigil

99

100

This can be thought of as the "HEAD" branch in CVS terms, or as the "trunk"

101

in Subversion terms. We typically call this the ``dev`` branch.

102

103

I prefer working in a subdirectory of ``$HOME`` to avoid collisions with all

104

the other stuff that ends up in ``$HOME``. Also, we will want a project

105

directory where we can hold all of the different branches we end up

106

working on::

107

108

% cd ~

109

% mkdir work

110

% cd work

111

% mkdir sigil

112

% cd sigil

113

% bzr checkout sftp://centralhost/srv/bzr/sigil dev

114

% cd dev

115

% cp -ar ~/sigil/* .

116

% bzr add

117

% bzr commit -m "Initial import of Sigil"

118

119

There are many ways to setup your working directory, but the above way

120

will makes it easy to handle working with feature/bugfix branches. And one

121

of the strong points of Bazaar_ is how well it works with branches.

122

123

At this point, because you have a 'checkout' of the remote branch, any

124

commits you make in ``dev/`` will automatically be saved both locally,

125

and on ``centralhost``.

126

127

128

Developer N: Getting a working copy of the project

129

--------------------------------------------------

130

131

Since the first developer did all of the work of creating the project,

132

all other developers can just get a checkout of that branch. They should

133

still follow `Setting User Email`_ and `Setting up a local Repository`_.

134

135

Then to get a copy of the current tip::

136

137

% cd ~/work/sigil

138

% bzr checkout sftp://centralhost/srv/bzr/sigil dev

139

140

Now that two people both have a checkout of

141

``sftp://centralhost/srv/bzr/sigil``, there will be times when one of

142

them is out of date with the current version. Bazaar_ will inform the user

143

of this and prevent them from committing. To get up to date use ``bzr

144

update``, which will update the tree with the remote changes. This may

145

require resolving conflicts, in the case that the same files have been

146

modified.

147

148

149

Developing on separate branches

150

===============================

151

152

So far everyone is working and committing their changes into the same

153

branch. Which means that everyone needs to update fairly regularly, and

154

deal with other people's changes. Also, if one person commits something

155

which breaks the codebase, then everyone has to deal with it.

156

157

Usually, it is better to do development on individual branches, and then

158

integrate those back into the main branch, once they are stable. This is

159

one of the biggest changes from working with CVS/SVN. They both allow you

160

to work on separate branches, but their merging algorithms are fairly

161

weak, so it is difficult to keep things synchronized. Bazaar_ merges track

162

what has already been merged, and can even apply changes to files that

163

have been renamed.

164

165

166

Creating and working on a new branch

167

------------------------------------

168

169

We want to keep our changes available for other people, even if they

170

aren't quite complete yet. So we will create a new public branch, and

171

track it locally.::

172

173

% cd ~/work/sigil

174

% bzr branch sftp://centralhost/srv/bzr/sigil \

175

sftp://centralhost/srv/bzr/sigil/doodle-fixes

176

% bzr checkout sftp://centralhost/srv/bzr/sigil/doodle-fixes doodle-fixes

177

% cd doodle-fixes

178

179

We now have a place to make any fixes to doodles that we need. And we

180

won't interrupt people who are working on other parts of the code.

181

Because we have a checkout, any commits made in the ``doodle-fixes/`` will

182

also show up on ``centralhost``. [#nestedbranches_]

183

It is also completely possible to have 2 developers collaborate on one of

184

these branches, just like they would have collaborated on the ``dev``

185

branch.[#cbranch]_

186

187

.. [#cbranch] When using lots of independent branches, having to retype

188

the full URL all the time takes a lot of typing. We are looking into

189

various methods to help with this, such as branch aliases, etc. For

190

now, though, the bzrtools_ plugin provides the ``bzr cbranch`` command.

191

Which is designed to take a base branch, create a new public branch,

192

and create a checkout of that branch, all with much less typing.

193

Configuring ``cbranch`` is outside the scope of this document, but the

194

final commands look like ``bzr cbranch dev my-feature-branch``

195

196

.. [#nestedbranches] It may look odd to have a branch in a subdirectory of

197

another branch. However, this is just fine, and you can think of it as

198

a heirarchial namespace. Where the nested branch is derived from the

199

outer branch.

200

201

.. _bzrtools: https://launchpad.net/products/bzrtools

202

203

204

Merging changes back

205

--------------------

206

207

When it is decided that some of the changes in ``doodle-fixes`` is ready

208

to be merged into the main tree, simply do::

209

210

% cd ~/work/sigil/dev

211

% bzr merge ../doodle-fixes

212

213

Now the changes are available in the ``dev`` branch, but they haven't been

214

committed yet. This is the time when you want to review the final changes,

215

and make sure they are what you want. ``bzr status`` and ``bzr diff`` are

216

good tools to use here. Also, there may be some conflicts in files, if

217

there were changes made to the same file. Bazaar_ will prevent you from

218

committing until you have resolved these conflicts. That way you don't

219

accidentally commit the conflict markers. ``bzr status`` will show the

220

conflicts along with the other changes, or you can use ``bzr conflicts``

221

to just list conflicts. Use ``bzr resolve file/name`` or ``bzr resolve

222

--all`` once conflicts have been handled.[#resolve]_

223

If you have a conflict that is particularly difficult to solve you may

224

want to use the ``bzr remerge`` command. It will let you try different

225

merge algorithms, as well as let you see the original source lines

226

(``--show-base``).

227

228

.. [#resolve] Some systems make you resolve conflicts as part of the merge

229

process. We have found that it is usually easier to resolve conflicts

230

when you have the view of the entire tree, rather than just a single

231

file. It gives you much more context, and also lets you run tests as

232

you resolve the problems.

233

234

235

Recommended Branching

236

---------------------

237

238

One very common way to handle all of these branches is to give each

239

developer their own branch, and their own place to work in the central

240

location. This can be done with::

241

242

% bzr branch sftp://centralhost/srv/bzr/sigil \

243

sftp://centralhost/srv/bzr/sigil/user-a

244

% bzr branch sftp://centralhost/srv/bzr/sigil \

245

sftp://centralhost/srv/bzr/sigil/user-b

246

247

This gives each developer their own branch to work on. And, they can

248

easily create a new feature branch for themselves with just[#cbranch]_::

249

250

% bzr branch sftp://centralhost/srv/bzr/sigil/user-a \

251

sftp://centralhost/srv/bzr/sigil/user-a/feature

252

% cd ~/work/sigil

253

% bzr checkout sftp://centralhost/srv/bzr/sigil/user-a/feature myfeature

254

255

256

Glossary

257

========

258

259

Shared Repository

260

-----------------

261

262

Bazaar_ has the concept of a `Shared Repository`_. This is similar to the

263

concept of other RCS's repository. Such as in Subversion, where you have a

264

remote repository, which is where all of the history is stored, and

265

locally you don't have any history information, only a checkout of the

266

working tree files. Note that "Shared" in this context means shared

267

between branches. It *may* be shared between people, but standalone

268

branches can also be shared between people.

269

270

In Bazaar_ terms, a `Shared Repository`_ is a location where multiple

271

branches can **share** their revision history information. Because Bazaar_

272

wants to support decentralized workflows, it is possible for every branch

273

to maintain its own revision history information. But this is often

274

inefficient, since often branches share history, and they might as well

275

share the storage as well.

276

277

278

..

279

vim: tw=74 ft=rst spell spelllang=en_us