73
82
Bazaar Development in a Nutshell
74
83
================================
76
Looking for a 10 minute introduction to submitting a change?
77
See http://bazaar-vcs.org/BzrGivingBack.
79
TODO: Merge that Wiki page into this document.
85
.. was from bazaar-vcs.org/BzrGivingBack
87
One of the fun things about working on a version control system like Bazaar is
88
that the users have a high level of proficiency in contributing back into
89
the tool. Consider the following very brief introduction to contributing back
90
to Bazaar. More detailed instructions are in the following sections.
95
First, get a local copy of the development mainline (See `Why make a local
101
$ bzr branch http://bazaar-vcs.org/bzr/bzr.dev/ bzr.dev
103
Now make your own branch::
105
$ bzr branch bzr.dev 123456-my-bugfix
107
This will give you a branch called "123456-my-bugfix" that you can work on
108
and commit in. Here, you can study the code, make a fix or a new feature.
109
Feel free to commit early and often (after all, it's your branch!).
111
Documentation improvements are an easy place to get started giving back to the
112
Bazaar project. The documentation is in the `doc/` subdirectory of the Bazaar
115
When you are done, make sure that you commit your last set of changes as well!
116
Once you are happy with your changes, ask for them to be merged, as described
119
Making a Merge Proposal
120
-----------------------
122
The Bazaar developers use Launchpad to further enable a truly distributed
123
style of development. Anyone can propose a branch for merging into the Bazaar
124
trunk. To start this process, you need to push your branch to Launchpad. To
125
do this, you will need a Launchpad account and user name, e.g.
126
`your_lp_username`. You can push your branch to Launchpad directly from
129
$ bzr push lp:~your_lp_username/bzr/giveback
131
After you have pushed your branch, you will need to propose it for merging to
132
the Bazaar trunk. Go to <https://launchpad.net/your_lp_username/bzr/giveback>
133
and choose "Propose for merging into another branch". Select "~bzr/bzr/trunk"
134
to hand your changes off to the Bazaar developers for review and merging.
136
Why make a local copy of bzr.dev?
137
---------------------------------
139
Making a local mirror of bzr.dev is not strictly necessary, but it means
141
- You can use that copy of bzr.dev as your main bzr executable, and keep it
142
up-to-date using ``bzr pull``.
143
- Certain operations are faster, and can be done when offline. For example:
146
- ``bzr diff -r ancestor:...``
149
- When it's time to create your next branch, it's more convenient. When you
150
have further contributions to make, you should do them in their own branch::
153
$ bzr branch bzr.dev additional_fixes
154
$ cd additional_fixes # hack, hack, hack
82
158
Understanding the Development Process
83
159
=====================================
85
The development team follows many best-practices including:
161
The development team follows many practices including:
87
163
* a public roadmap and planning process in which anyone can participate
108
184
For further information, see http://bazaar-vcs.org/BzrDevelopment.
111
A Closer Look at the Merge & Review Process
112
===========================================
114
If you'd like to propose a change, please post to the
115
bazaar@lists.canonical.com list with a bundle, patch, or link to a
116
branch. Put '[PATCH]' or '[MERGE]' in the subject so Bundle Buggy
117
can pick it out, and explain the change in the email message text.
118
Remember to update the NEWS file as part of your change if it makes any
119
changes visible to users or plugin developers. Please include a diff
120
against mainline if you're giving a link to a branch.
122
You can generate a bundle like this::
124
bzr bundle > mybundle.patch
126
A .patch extension is recommended instead of .bundle as many mail clients
127
will send the latter as a binary file. If a bundle would be too long or your
128
mailer mangles whitespace (e.g. implicitly converts Unix newlines to DOS
129
newlines), use the merge-directive command instead like this::
131
bzr merge-directive http://bazaar-vcs.org http://example.org/my_branch > my_directive.patch
133
See the help for details on the arguments to merge-directive.
135
Please do **NOT** put [PATCH] or [MERGE] in the subject line if you don't
136
want it to be merged. If you want comments from developers rather than
137
to be merged, you can put '[RFC]' in the subject line.
139
Anyone is welcome to review code. There are broadly three gates for
142
* Doesn't reduce test coverage: if it adds new methods or commands,
143
there should be tests for them. There is a good test framework
144
and plenty of examples to crib from, but if you are having trouble
145
working out how to test something feel free to post a draft patch
148
* Doesn't reduce design clarity, such as by entangling objects
149
we're trying to separate. This is mostly something the more
150
experienced reviewers need to help check.
152
* Improves bugs, features, speed, or code simplicity.
154
Code that goes in should pass all three. The core developers take care
155
to keep the code quality high and understandable while recognising that
156
perfect is sometimes the enemy of good. (It is easy for reviews to make
157
people notice other things which should be fixed but those things should
158
not hold up the original fix being accepted. New things can easily be
159
recorded in the Bug Tracker instead.)
161
Anyone can "vote" on the mailing list. Core developers can also vote using
162
Bundle Buggy. Here are the voting codes and their explanations.
164
:approve: Reviewer wants this submission merged.
165
:tweak: Reviewer wants this submission merged with small changes. (No
167
:abstain: Reviewer does not intend to vote on this patch.
168
:resubmit: Please make changes and resubmit for review.
169
:reject: Reviewer doesn't want this kind of change merged.
170
:comment: Not really a vote. Reviewer just wants to comment, for now.
172
If a change gets two approvals from core reviewers, and no rejections,
173
then it's OK to come in. Any of the core developers can bring it into the
174
bzr.dev trunk and backport it to maintenance branches if required. The
175
Release Manager will merge the change into the branch for a pending
176
release, if any. As a guideline, core developers usually merge their own
177
changes and volunteer to merge other contributions if they were the second
178
reviewer to agree to a change.
180
To track the progress of proposed changes, use Bundle Buggy. See
181
http://bundlebuggy.aaronbentley.com/help for a link to all the
182
outstanding merge requests together with an explanation of the columns.
183
Bundle Buggy will also mail you a link to track just your change.
186
189
Preparing a Sandbox for Making Changes to Bazaar
255
258
is in the ReStructuredText markup language.
258
Documentation specifically targetted at Bazaar and plugin developers.
261
Documentation specifically targeted at Bazaar and plugin developers.
259
262
(Including this document.)
263
266
Automatically-generated API reference information is available at
264
267
<http://starship.python.net/crew/mwh/bzrlibapi/>.
265
(There is an experimental editable version at
266
<http://starship.python.net/crew/mwh/bzrlibapi-oe/>.)
267
See also the `Essential Domain Classes`_
268
section of this guide.
271
Essential Domain Classes
272
########################
274
Introducing the Object Model
269
See also the `Bazaar Architectural Overview <../../developers/overview.html>`_.
272
The Code Review Process
273
#######################
275
All code changes coming in to Bazaar are reviewed by someone else.
276
Normally changes by core contributors are reviewed by one other core
277
developer, and changes from other people are reviewed by two core
278
developers. Use intelligent discretion if the patch is trivial.
280
Good reviews do take time. They also regularly require a solid
281
understanding of the overall code base. In practice, this means a small
282
number of people often have a large review burden - with knowledge comes
283
responsibility. No one likes their merge requests sitting in a queue going
284
nowhere, so reviewing sooner rather than later is strongly encouraged.
293
Please put a "cover letter" on your merge request explaining:
295
* the reason **why** you're making this change
297
* **how** this change achieves this purpose
299
* anything else you may have fixed in passing
301
* anything significant that you thought of doing, such as a more
302
extensive fix or a different approach, but didn't or couldn't do now
304
A good cover letter makes reviewers' lives easier because they can decide
305
from the letter whether they agree with the purpose and approach, and then
306
assess whether the patch actually does what the cover letter says.
307
Explaining any "drive-by fixes" or roads not taken may also avoid queries
308
from the reviewer. All in all this should give faster and better reviews.
309
Sometimes writing the cover letter helps the submitter realize something
310
else they need to do. The size of the cover letter should be proportional
311
to the size and complexity of the patch.
314
Reviewing proposed changes
315
==========================
317
Anyone is welcome to review code, and reply to the thread with their
320
The simplest way to review a proposed change is to just read the patch on
321
the list or in Bundle Buggy. For more complex changes it may be useful
322
to make a new working tree or branch from trunk, and merge the proposed
323
change into it, so you can experiment with the code or look at a wider
326
There are three main requirements for code to get in:
328
* Doesn't reduce test coverage: if it adds new methods or commands,
329
there should be tests for them. There is a good test framework
330
and plenty of examples to crib from, but if you are having trouble
331
working out how to test something feel free to post a draft patch
334
* Doesn't reduce design clarity, such as by entangling objects
335
we're trying to separate. This is mostly something the more
336
experienced reviewers need to help check.
338
* Improves bugs, features, speed, or code simplicity.
340
Code that goes in should not degrade any of these aspects. Patches are
341
welcome that only cleanup the code without changing the external
342
behaviour. The core developers take care to keep the code quality high
343
and understandable while recognising that perfect is sometimes the enemy
346
It is easy for reviews to make people notice other things which should be
347
fixed but those things should not hold up the original fix being accepted.
348
New things can easily be recorded in the Bug Tracker instead.
350
It's normally much easier to review several smaller patches than one large
351
one. You might want to use ``bzr-loom`` to maintain threads of related
352
work, or submit a preparatory patch that will make your "real" change
356
Checklist for reviewers
357
=======================
359
* Do you understand what the code's doing and why?
361
* Will it perform reasonably for large inputs, both in memory size and
362
run time? Are there some scenarios where performance should be
365
* Is it tested, and are the tests at the right level? Are there both
366
blackbox (command-line level) and API-oriented tests?
368
* If this change will be visible to end users or API users, is it
369
appropriately documented in NEWS?
371
* Does it meet the coding standards below?
373
* If it changes the user-visible behaviour, does it update the help
374
strings and user documentation?
376
* If it adds a new major concept or standard practice, does it update the
377
developer documentation?
379
* (your ideas here...)
385
From May 2009 on, we prefer people to propose code reviews through
388
* <https://launchpad.net/+tour/code-review>
390
* <https://help.launchpad.net/Code/Review>
392
Anyone can propose or comment on a merge proposal just by creating a
395
There are two ways to create a new merge proposal: through the web
396
interface or by email.
399
Proposing a merge through the web
400
---------------------------------
402
To create the proposal through the web, first push your branch to Launchpad.
403
For example, a branch dealing with documentation belonging to the Launchpad
404
User mbp could be pushed as ::
406
bzr push lp:~mbp/bzr/doc
408
Then go to the branch's web page, which in this case would be
409
<https://code.launchpad.net/~mbp/bzr/doc>. You can simplify this step by just
414
You can then click "Propose for merging into another branch", and enter your
415
cover letter (see above) into the web form. Typically you'll want to merge
416
into ``~bzr/bzr/trunk`` which will be the default; you might also want to
417
nominate merging into a release branch for a bug fix. There is the option to
418
specify a specific reviewer or type of review, and you shouldn't normally
421
Submitting the form takes you to the new page about the merge proposal
422
containing the diff of the changes, comments by interested people, and
423
controls to comment or vote on the change.
425
Proposing a merge by mail
426
-------------------------
428
To propose a merge by mail, send a bundle to ``merge@code.launchpad.net``.
430
You can generate a merge request like this::
432
bzr send -o bug-1234.diff
434
``bzr send`` can also send mail directly if you prefer; see the help.
439
From <https://code.launchpad.net/bzr/+activereviews> you can see all
440
currently active reviews, and choose one to comment on. This page also
441
shows proposals that are now approved and should be merged by someone with
445
Reviews through Bundle Buggy
275
446
============================
277
The core domain objects within the bazaar model are:
287
Transports are explained below. See http://bazaar-vcs.org/Classes/
288
for an introduction to the other key classes.
293
The ``Transport`` layer handles access to local or remote directories.
294
Each Transport object acts like a logical connection to a particular
295
directory, and it allows various operations on files within it. You can
296
*clone* a transport to get a new Transport connected to a subdirectory or
299
Transports are not used for access to the working tree. At present
300
working trees are always local and they are accessed through the regular
301
Python file io mechanisms.
306
Transports work in URLs. Take note that URLs are by definition only
307
ASCII - the decision of how to encode a Unicode string into a URL must be
308
taken at a higher level, typically in the Store. (Note that Stores also
309
escape filenames which cannot be safely stored on all filesystems, but
310
this is a different level.)
312
The main reason for this is that it's not possible to safely roundtrip a
313
URL into Unicode and then back into the same URL. The URL standard
314
gives a way to represent non-ASCII bytes in ASCII (as %-escapes), but
315
doesn't say how those bytes represent non-ASCII characters. (They're not
316
guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
318
For example if the user enters the url ``http://example/%e0`` there's no
319
way to tell whether that character represents "latin small letter a with
320
grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2
321
or malformed UTF-8. So we can't convert their URL to Unicode reliably.
323
Equally problematic if we're given a url-like string containing non-ascii
324
characters (such as the accented a) we can't be sure how to convert that
325
to the correct URL, because we don't know what encoding the server expects
326
for those characters. (Although this is not totally reliable we might still
327
accept these and assume they should be put into UTF-8.)
329
A similar edge case is that the url ``http://foo/sweet%2Fsour`` contains
330
one directory component whose name is "sweet/sour". The escaped slash is
331
not a directory separator. If we try to convert URLs to regular Unicode
332
paths this information will be lost.
334
This implies that Transports must natively deal with URLs; for simplicity
335
they *only* deal with URLs and conversion of other strings to URLs is done
336
elsewhere. Information they return, such as from ``list_dir``, is also in
337
the form of URL components.
448
The Bundle Buggy tool used up to May 2009 is still available as a review
451
Sending patches for review
452
--------------------------
454
If you'd like to propose a change, please post to the
455
bazaar@lists.canonical.com list with a bundle, patch, or link to a
456
branch. Put ``[PATCH]`` or ``[MERGE]`` in the subject so Bundle Buggy
457
can pick it out, and explain the change in the email message text.
458
Remember to update the NEWS file as part of your change if it makes any
459
changes visible to users or plugin developers. Please include a diff
460
against mainline if you're giving a link to a branch.
462
You can generate a merge request like this::
464
bzr send -o bug-1234.patch
466
A ``.patch`` extension is recommended instead of .bundle as many mail clients
467
will send the latter as a binary file.
469
``bzr send`` can also send mail directly if you prefer; see the help.
471
Please do **NOT** put [PATCH] or [MERGE] in the subject line if you don't
472
want it to be merged. If you want comments from developers rather than
473
to be merged, you can put ``[RFC]`` in the subject line.
475
If this change addresses a bug, please put the bug number in the subject
476
line too, in the form ``[#1]`` so that Bundle Buggy can recognize it.
478
If the change is intended for a particular release mark that in the
479
subject too, e.g. ``[1.6]``.
480
Anyone can "vote" on the mailing list by expressing an opinion. Core
481
developers can also vote using Bundle Buggy. Here are the voting codes and
484
:approve: Reviewer wants this submission merged.
485
:tweak: Reviewer wants this submission merged with small changes. (No
487
:abstain: Reviewer does not intend to vote on this patch.
488
:resubmit: Please make changes and resubmit for review.
489
:reject: Reviewer doesn't want this kind of change merged.
490
:comment: Not really a vote. Reviewer just wants to comment, for now.
492
If a change gets two approvals from core reviewers, and no rejections,
493
then it's OK to come in. Any of the core developers can bring it into the
494
bzr.dev trunk and backport it to maintenance branches if required. The
495
Release Manager will merge the change into the branch for a pending
496
release, if any. As a guideline, core developers usually merge their own
497
changes and volunteer to merge other contributions if they were the second
498
reviewer to agree to a change.
500
To track the progress of proposed changes, use Bundle Buggy. See
501
http://bundlebuggy.aaronbentley.com/help for a link to all the
502
outstanding merge requests together with an explanation of the columns.
503
Bundle Buggy will also mail you a link to track just your change.
340
505
Coding Style Guidelines
341
506
#######################
added
removed
doc/en/developer-guide/HACKING.txt
