« back to all changes in this revision
Viewing changes to doc/centralized_workflow.txt
- browse files at revision 2100
- compare with another revision
- compare with revision 6141
- download diff
- download tarball
- view history from revision 2100
- Committer: Canonical.com Patch Queue Manager
- Date: 2006-10-27 22:52:41 UTC
- mfrom: (2098.2.2 centralized_doc)
- Revision ID: pqm@pqm.ubuntu.com-20061027225241-7339e4c92f55536c
(Alaa Salman, John Arbash Meinel) Cleanup the centralized_workflow.txt document
- files modified:
- doc/centralized_workflow.txt
added
removed
doc/centralized_workflow.txt
2
2
Centralized Workflow
3
3
====================
4
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.
5
I- Overview
6
===========
7
8
This document describes a possible workflow for using Bazaar_. That of
9
using Bazaar_, the distributed version control system, in a centralized
10
manner. Bazaar_ is designed to be very flexible and allows several
11
different workflows, from fully decentralized to mostly centralized. The
12
workflow used here is meant to ease a new user into more advanced usage of
13
Bazaar_, and allows them to work in a mix of centralized and decentralized
14
operations.
15
16
In general, this document is meant for users coming from a background of
17
centralized version control systems such as CVS or subversion. It is
18
common in work settings to have a single central server hosting the
19
codebase, with several people working on this codebase, keeping their work
20
in sync. This workflow is also applicable to a single developer working
21
on several different machines.
22
22
23
23
.. _Bazaar: http://bazaar-vcs.org
24
24
25
25
26
Initial Setup
27
=============
26
II- Initial Setup
27
=================
28
28
29
29
These are some reasonably simple steps to setup Bazaar_ so that it works
30
30
well for you.
31
31
32
32
33
Setting User Email
34
------------------
33
1- Setting User Email
34
---------------------
35
35
36
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
-----------------------------
37
be accurate or unique, it will be used in log messages and
38
annotations, so it is better to have something real.
39
40
::
41
42
% bzr whoami "John Doe <jdoe@organization.com>"
43
44
45
2- Setting up a local Repository
46
--------------------------------
45
47
46
48
Bazaar_ branches generally copy the history information around with them,
47
49
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.
50
optimization, it is possible for related branches to combine their storage
51
needs so that you do not need to copy around all of this history
52
information whenever you create a new branch.
51
53
52
54
The best way to do this is to create a `Shared Repository`_. In general,
53
55
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
56
`Shared Repository`_. So let's setup a `Shared Repository`_ in our home
55
57
directory, thus all branches we create underneath will share their history
56
storage.::
58
storage.
59
60
::
57
61
58
62
% bzr init-repo --trees ~
59
63
60
64
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.::
65
3- Setting up a remote Repository
66
---------------------------------
67
68
Many times you want a location where data is stored separately from where
69
you do your work. This workflow is required by centralized systems
70
(CVS/SVN). Usually they are on separate machines, but not always. This is
71
actually a pretty good setup, especially in a work environment. Since it
72
ensures a central location where data can be backed up, and means that if
73
something happens to a developer's machine, no committed work has to be
74
lost.
75
76
So let's set up a shared location for our project on a remote machine
77
called ``centralhost``. Again, we will use a
78
`Shared Repository`_ to optimize disk usage.
79
80
::
73
81
74
82
% bzr init-repo --no-trees sftp://centralhost/srv/bzr/
75
83
76
84
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
subversion repository.
86
87
88
III- Versioning an existing project
89
===================================
90
91
Now that we have a repository, let's create a versioned project. Most of
92
the time, you will already have some code that you are working with,
85
93
that you now want to version using Bazaar_. If the code was originally
86
94
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
----------------------------------------
95
without losing any history. However, this is outside the scope of this
96
document. See `Tracking Upstream`_ for some possibilities (section
97
"Converting and keeping history").
98
99
.. _Tracking Upstream: http://bazaar-vcs.org/TrackingUpstream
100
101
..
102
XXX: We really need a different document for discussing conversion of a
103
project. Right now TrackingUpstream is the best we have, though.
104
105
106
1- Developer 1: Creating the first revision
107
-------------------------------------------
93
108
94
109
So first, we want to create a branch in our remote Repository, where we
95
110
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::
111
"sigil" that we want to start versioning.
112
113
::
97
114
98
115
% bzr init sftp://centralhost/srv/bzr/sigil
99
116
100
117
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.
118
in Subversion terms. We will call this the ``dev`` branch.
102
119
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
120
I prefer working in a subdirectory of my home directory to avoid collisions with all
121
the other files that end up there. Also, we will want a project
105
122
directory where we can hold all of the different branches we end up
106
working on::
123
working on.
124
125
::
107
126
108
127
% cd ~
109
128
% mkdir work
116
135
% bzr add
117
136
% bzr commit -m "Initial import of Sigil"
118
137
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
138
139
In the example above, we created an empty branch (the ``/sigil`` branch)
140
on ``centralhost``, and then checkout out this empty branch onto our
141
workstation to add files from our existing project.
142
There are many ways to setup your working directory, but the steps above
143
make it easy to handle working with feature/bugfix branches. And one
121
144
of the strong points of Bazaar_ is how well it works with branches.
122
145
123
146
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,
147
commits you make in ``~/work/sigil/dev/`` will automatically be saved both locally,
125
148
and on ``centralhost``.
126
149
127
150
128
Developer N: Getting a working copy of the project
129
--------------------------------------------------
151
2- Developer N: Getting a working copy of the project
152
-----------------------------------------------------
130
153
131
154
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`_.
155
all other developers would just checkout that branch. **They should
156
still follow** `1- Setting User Email`_ and `2- Setting up a local Repository`_.
134
157
135
Then to get a copy of the current tip::
158
To get a copy of the current development tree::
136
159
137
160
% cd ~/work/sigil
138
161
% bzr checkout sftp://centralhost/srv/bzr/sigil dev
139
162
140
163
Now that two people both have a checkout of
141
164
``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
===============================
165
the checkouts will be out of date with the current version.
166
At commit time, Bazaar_ will inform the user of this and prevent them from
167
committing. To get up to date, use ``bzr update`` to update the
168
tree with the remote changes. This may require resolving conflicts, if the
169
same files have been modified.
170
171
172
IV- Developing on separate branches
173
===================================
151
174
152
175
So far everyone is working and committing their changes into the same
153
branch. Which means that everyone needs to update fairly regularly, and
176
branch. This means that everyone needs to update fairly regularly and
154
177
deal with other people's changes. Also, if one person commits something
155
which breaks the codebase, then everyone has to deal with it.
178
that breaks the codebase, then upon syncing, everyone will get the
179
problem.
156
180
157
Usually, it is better to do development on individual branches, and then
181
Usually, it is better to do development on different branches, and then
158
182
integrate those back into the main branch, once they are stable. This is
159
183
one of the biggest changes from working with CVS/SVN. They both allow you
160
184
to work on separate branches, but their merging algorithms are fairly
161
weak, so it is difficult to keep things synchronized. Bazaar_ merges track
185
weak, so it is difficult to keep things synchronized. Bazaar_ tracks
162
186
what has already been merged, and can even apply changes to files that
163
187
have been renamed.
164
188
165
189
166
Creating and working on a new branch
167
------------------------------------
190
1- Creating and working on a new branch
191
---------------------------------------
168
192
169
193
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.::
194
aren't quite complete yet. So we will create a new public branch on
195
``centralhost``, and track it locally.
196
197
::
172
198
173
199
% cd ~/work/sigil
174
200
% bzr branch sftp://centralhost/srv/bzr/sigil \
176
202
% bzr checkout sftp://centralhost/srv/bzr/sigil/doodle-fixes doodle-fixes
177
203
% cd doodle-fixes
178
204
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]_
205
We now have a place to make any fixes we need to ``doodle``. And we would
206
not interrupt people who are working on other parts of the code. Because
207
we have a checkout, any commits made in the ``~/work/sigil/doodle-fixes/``
208
will also show up on ``centralhost``. [#nestedbranches]_ It is also
209
possible to have 2 developers collaborate on one of these branches, just
210
like they would have collaborated on the ``dev`` branch. [#cbranch]_
211
212
.. [#nestedbranches] It may look odd to have a branch in a subdirectory of
213
another branch. This is just fine, and you can think of it as a
214
heirarchial namespace. Where the nested branch is derived from the
215
outer branch.
186
216
187
217
.. [#cbranch] When using lots of independent branches, having to retype
188
218
the full URL all the time takes a lot of typing. We are looking into
193
223
Configuring ``cbranch`` is outside the scope of this document, but the
194
224
final commands look like ``bzr cbranch dev my-feature-branch``
195
225
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
226
.. _bzrtools: https://launchpad.net/products/bzrtools
202
227
203
228
204
Merging changes back
205
--------------------
229
2- Merging changes back
230
-----------------------
206
231
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::
232
When it is decided that some of the changes in ``doodle-fixes`` are ready
233
to be merged into the main branch, simply do::
209
234
210
235
% cd ~/work/sigil/dev
211
236
% bzr merge ../doodle-fixes
212
237
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``).
238
Now the changes are available in the ``dev`` branch, but they have not
239
been committed yet. This is the time when you want to review the final
240
changes, and double check the code to make sure it compiles cleanly and
241
passes the test suite. The commands ``bzr status`` and ``bzr diff`` are
242
good tools to use here. Also, this is the time to resolve any conflicts.
243
Bazaar_ will prevent you from committing until you have resolved these
244
conflicts. That way you don't accidentally commit the conflict markers.
245
The command ``bzr status`` will show the conflicts along with the other
246
changes, or you can use ``bzr conflicts`` to just list conflicts. Use
247
``bzr resolve file/name`` or ``bzr resolve --all`` once conflicts have
248
been handled. [#resolve]_ If you have a conflict that is particularly
249
difficult to solve you may want to use the ``bzr remerge`` command. It
250
will let you try different merge algorithms, as well as let you see the
251
original source lines (``--show-base``).
227
252
228
253
.. [#resolve] Some systems make you resolve conflicts as part of the merge
229
254
process. We have found that it is usually easier to resolve conflicts
232
257
you resolve the problems.
233
258
234
259
235
Recommended Branching
236
---------------------
260
V- Recommended Branching
261
------------------------
237
262
238
263
One very common way to handle all of these branches is to give each
239
264
developer their own branch, and their own place to work in the central
253
278
% bzr checkout sftp://centralhost/srv/bzr/sigil/user-a/feature myfeature
254
279
255
280
256
Glossary
257
========
281
VI- Glossary
282
============
258
283
259
284
Shared Repository
260
285
-----------------
261
286
262
Bazaar_ has the concept of a `Shared Repository`_. This is similar to the
287
Bazaar_ has the concept of a "Shared Repository". This is similar to the
263
288
concept of other RCS's repository. Such as in Subversion, where you have a
264
289
remote repository, which is where all of the history is stored, and
265
290
locally you don't have any history information, only a checkout of the
267
292
between branches. It *may* be shared between people, but standalone
268
293
branches can also be shared between people.
269
294
270
In Bazaar_ terms, a `Shared Repository`_ is a location where multiple
295
In Bazaar_ terms, a "Shared Repository" is a location where multiple
271
296
branches can **share** their revision history information. Because Bazaar_
272
297
wants to support decentralized workflows, it is possible for every branch
273
298
to maintain its own revision history information. But this is often
274
inefficient, since often branches share history, and they might as well
299
inefficient, since related branches share history, and they might as well
275
300
share the storage as well.
276
301
277
302
Loggerhead is a web-based interface for Breezy
Version: 2.0.1