← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/user-guide/zen.txt

  • Committer: Patch Queue Manager
  • Date: 2012-07-10 11:26:46 UTC
  • mfrom: (6535.1.1 trunk)
  • Revision ID: pqm@pqm.ubuntu.com-20120710112646-82a24oyibuwi0ofl
(vila) Release 2.6b2 (Vincent Ladeuil)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/zen.txt
 
1
Bazaar Zen
 
2
==========
 
3
 
 
4
Grokking Bazaar
 
5
---------------
 
6
 
 
7
While Bazaar is similar to other VCS tools in many ways, there are
 
8
some important differences that are not necessarily obvious at first
 
9
glance.  This section attempts
 
10
to explain some of the things users need to know in order to "grok" Bazaar,
 
11
i.e. to deeply understand it.
 
12
 
 
13
Note: It isn't necessary to fully understand this section to use Bazaar.
 
14
You may wish to skim this section now and come back to it at a later time.
 
15
 
 
16
Understanding revision numbers
 
17
------------------------------
 
18
 
 
19
All revisions in the mainline of a branch have a simple increasing
 
20
integer. (First commit gets 1, 10th commit gets 10, etc.) This makes them
 
21
fairly natural to use when you want to say "grab the 10th revision from my
 
22
branch", or "fixed in revision 3050".
 
23
 
 
24
For revisions which have been merged into a branch, a dotted notation is used
 
25
(e.g., 3112.1.5). Dotted revision numbers have three numbers [#]_. The first
 
26
number indicates what mainline revision change is derived from. The second
 
27
number is the branch counter. There can be many branches derived from the
 
28
same revision, so they all get a unique number. The third number is the
 
29
number of revisions since the branch started. For example, 3112.1.5 is the
 
30
first branch from revision 3112, the fifth revision on that branch.
 
31
 
 
32
.. [#] Versions prior to bzr 1.2 used a slightly different algorithm.
 
33
   Some nested branches would get extra numbers (such as 1.1.1.1.1)
 
34
   rather than the simpler 3-number system.
 
35
 
 
36
Hierarchical history is good
 
37
----------------------------
 
38
 
 
39
Imagine a project with multiple developers contributing changes where
 
40
many changes consist of a series of commits. To give a concrete example,
 
41
consider the case where:
 
42
 
 
43
 * The tip of the project's trunk is revision 100.
 
44
 * Mary makes 3 changes to deliver feature X.
 
45
 * Bill makes 4 changes to deliver feature Y.
 
46
 
 
47
If the developers are working in parallel and using a traditional
 
48
centralized VCS approach, the project history will most likely be linear
 
49
with Mary's changes and Bill's changes interleaved. It might look like this::
 
50
 
 
51
  107: Add documentation for Y
 
52
  106: Fix bug found in testing Y
 
53
  105: Fix bug found in testing X
 
54
  104: Add code for Y
 
55
  103: Add documentation for X
 
56
  102: Add code and tests for X
 
57
  101: Add tests for Y
 
58
  100: ...
 
59
 
 
60
Many teams use this approach because their tools make branching and merging
 
61
difficult. As a consequence, developers update from and commit to the trunk
 
62
frequently, minimizing integration pain by spreading it over every commit.
 
63
If you wish, you can use Bazaar exactly like this. Bazaar does offer other
 
64
ways though that you ought to consider.
 
65
 
 
66
An alternative approach encouraged by distributed VCS tools is to create
 
67
feature branches and to integrate those when they are ready. In this case,
 
68
Mary's feature branch would look like this::
 
69
 
 
70
  103: Fix bug found in testing X
 
71
  102: Add documentation for X
 
72
  101: Add code and tests for X
 
73
  100: ...
 
74
 
 
75
And Bill's would look like this::
 
76
 
 
77
  104: Add documentation for Y
 
78
  103: Fix bug found in testing Y
 
79
  102: Add code for Y
 
80
  101: Add tests for Y
 
81
  100: ...
 
82
 
 
83
If the features were independent and you wanted to keep linear history,
 
84
the changes could be pushed back into the trunk in batches. (Technically,
 
85
there are several ways of doing that but that's beyond the scope of
 
86
this discussion.) The resulting history might look like this::
 
87
 
 
88
  107: Fix bug found in testing X
 
89
  106: Add documentation for X
 
90
  105: Add code and tests for X
 
91
  104: Add documentation for Y
 
92
  103: Fix bug found in testing Y
 
93
  102: Add code for Y
 
94
  101: Add tests for Y
 
95
  100: ...
 
96
 
 
97
While this takes a bit more effort to achieve, it has some advantages over
 
98
having revisions randomly intermixed. Better still though, branches can
 
99
be merged together forming a non-linear history. The result might look
 
100
like this::
 
101
 
 
102
  102: Merge feature X
 
103
       100.2.3: Fix bug found in testing X
 
104
       100.2.2: Add documentation for X
 
105
       100.2.1: Add code and tests for X
 
106
  101: Merge feature Y
 
107
       100.1.4: Add documentation for Y
 
108
       100.1.3: Fix bug found in testing Y
 
109
       100.1.2: Add code for Y
 
110
       100.1.1: Add tests for Y
 
111
  100: ...
 
112
 
 
113
Or more likely this::
 
114
 
 
115
  102: Merge feature X
 
116
       100.2.3: Fix bug
 
117
       100.2.2: Add documentation
 
118
       100.2.1: Add code and tests
 
119
  101: Merge feature Y
 
120
       100.1.4: Add documentation
 
121
       100.1.3: Fix bug found in testing
 
122
       100.1.2: Add code
 
123
       100.1.1: Add tests
 
124
  100: ...
 
125
 
 
126
This is considered good for many reasons:
 
127
 
 
128
 * It makes it easier to understand the history of a project.
 
129
   Related changes are clustered together and clearly partitioned.
 
130
 
 
131
 * You can easily collapse history to see just the commits on the mainline
 
132
   of a branch. When viewing the trunk history like this, you only see
 
133
   high level commits (instead of a large number of commits uninteresting
 
134
   at this level).
 
135
 
 
136
 * If required, it makes backing out a feature much easier.
 
137
 
 
138
 * Continuous integration tools can be used to ensure that
 
139
   all tests still pass before committing a merge to the mainline.
 
140
   (In many cases, it isn't appropriate to trigger CI tools after
 
141
   every single commit as some tests will fail during development.
 
142
   In fact, adding the tests first - TDD style - will guarantee it!)
 
143
 
 
144
In summary, the important points are:
 
145
 
 
146
  *Organize your work using branches.*
 
147
 
 
148
  *Integrate changes using merge.*
 
149
 
 
150
  *Ordered revision numbers and hierarchy make history easier to follow.*
 
151
 
 
152
 
 
153
Each branch has its own view of history
 
154
---------------------------------------
 
155
 
 
156
As explained above, Bazaar makes the distinction between:
 
157
 
 
158
 * mainline revisions, i.e. ones you committed in your branch, and
 
159
 
 
160
 * merged revisions, i.e. ones added as ancestors by committing a merge.
 
161
 
 
162
Each branch effectively has its own view of history, i.e. different
 
163
branches can give the same revision a different "local" revision number.
 
164
Mainline revisions always get allocated single number revision numbers
 
165
while merged revisions always get allocated dotted revision numbers.
 
166
 
 
167
To extend the example above, here's what the revision history of
 
168
Mary's branch would look like had she decided to merge the project
 
169
trunk into her branch after completing her changes::
 
170
 
 
171
  104: Merge mainline
 
172
       100.2.1: Merge feature Y
 
173
       100.1.4: Add documentation
 
174
       100.1.3: Fix bug found in testing
 
175
       100.1.2: Add code
 
176
       100.1.1: Add tests
 
177
  103: Fix bug found in testing X
 
178
  102: Add documentation for X
 
179
  101: Add code and tests for X
 
180
  100: ...
 
181
 
 
182
Once again, it's easy for Mary to look at just *her* top level of history
 
183
to see the steps she has taken to develop this change. In this context,
 
184
merging the trunk (and resolving any conflicts caused by doing that) is
 
185
just one step as far as the history of this branch is concerned.
 
186
 
 
187
It's important to remember that Bazaar is not changing history here, nor
 
188
is it changing the global revision identifiers. You can always use the
 
189
latter if you really want to. In fact, you can use the branch specific
 
190
revision numbers when communicating *as long as* you provide the branch
 
191
URL as context. (In many Bazaar projects, developers imply the central
 
192
trunk branch if they exchange a revision number without a branch URL.)
 
193
 
 
194
Merges do not change revision numbers in a branch, though they do
 
195
allocate local revision numbers to newly merged revisions. The only time
 
196
Bazaar will change revision numbers in a branch is when you explicitly
 
197
ask it to mirror another branch.
 
198
 
 
199
Note: Revisions are numbered in a stable way: if two branches have
 
200
the same revision in their mainline, all revisions in the ancestry of that
 
201
revision will have the same revision numbers. For example, if Alice and Bob's
 
202
branches agree on revision 10, they will agree on all revisions before
 
203
that.
 
204
 
 
205
Summary
 
206
-------
 
207
 
 
208
In general, if you follow the advice given earlier - organise
 
209
your work in branches and use merge to collaborate - you'll find Bazaar
 
210
generally does what you expect.
 
211
 
 
212
In coming chapters, we examine various ways of using Bazaar beginning with
 
213
the simplest: using Bazaar for personal projects.
 
214
 
 
215
..
 
216
   vim: ft=rst tw=74 ai