46
40
If nothing else, perhaps you'll find inspiration in how other developers
47
41
have solved their challenges.
43
Finding Something To Do
44
=======================
46
Ad-hoc performance work can also be done. One useful tool is the 'evil' debug
47
flag. For instance running ``bzr -Devil commit -m "test"`` will log a backtrace
48
to the bzr log file for every method call which triggers a slow or non-scalable
49
part of the bzr library. So checking that a given command with ``-Devil`` has
50
no backtraces logged to the log file is a good way to find problem function
51
calls that might be nested deep in the code base.
50
53
Planning and Discussing Changes
51
54
===============================
73
76
Bazaar Development in a Nutshell
74
77
================================
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.
79
.. was from bazaar-vcs.org/BzrGivingBack
81
One of the fun things about working on a version control system like Bazaar is
82
that the users have a high level of proficiency in contributing back into
83
the tool. Consider the following very brief introduction to contributing back
84
to Bazaar. More detailed instructions are in the following sections.
89
First, get a local copy of the development mainline (See `Why make a local
95
$ bzr branch http://bazaar-vcs.org/bzr/bzr.dev/ bzr.dev
97
Now make your own branch::
99
$ bzr branch bzr.dev 123456-my-bugfix
101
This will give you a branch called "123456-my-bugfix" that you can work on
102
and commit in. Here, you can study the code, make a fix or a new feature.
103
Feel free to commit early and often (after all, it's your branch!).
105
Documentation improvements are an easy place to get started giving back to the
106
Bazaar project. The documentation is in the `doc/` subdirectory of the Bazaar
109
When you are done, make sure that you commit your last set of changes as well!
110
Once you are happy with your changes, ask for them to be merged, as described
113
Making a Merge Proposal
114
-----------------------
116
The Bazaar developers use Launchpad to further enable a truly distributed
117
style of development. Anyone can propose a branch for merging into the Bazaar
118
trunk. To start this process, you need to push your branch to Launchpad. To
119
do this, you will need a Launchpad account and user name, e.g.
120
`your_lp_username`. You can push your branch to Launchpad directly from
123
$ bzr push lp:~your_lp_username/bzr/meaningful_name_here
125
After you have pushed your branch, you will need to propose it for merging to
126
the Bazaar trunk. Go to
127
<https://launchpad.net/your_lp_username/bzr/meaningful_name_here> and choose
128
"Propose for merging into another branch". Select "~bzr/bzr/trunk" to hand
129
your changes off to the Bazaar developers for review and merging.
131
Using a meaningful name for your branch will help you and the reviewer(s)
132
better track the submission. Use a very succint description of your submission
133
and prefix it with bug number if needed (lp:~mbp/bzr/484558-merge-directory
134
for example). Alternatively, you can suffix with the bug number
135
(lp:~jameinel/bzr/export-file-511987).
138
Why make a local copy of bzr.dev?
139
---------------------------------
141
Making a local mirror of bzr.dev is not strictly necessary, but it means
143
- You can use that copy of bzr.dev as your main bzr executable, and keep it
144
up-to-date using ``bzr pull``.
145
- Certain operations are faster, and can be done when offline. For example:
148
- ``bzr diff -r ancestor:...``
151
- When it's time to create your next branch, it's more convenient. When you
152
have further contributions to make, you should do them in their own branch::
155
$ bzr branch bzr.dev additional_fixes
156
$ cd additional_fixes # hack, hack, hack
82
160
Understanding the Development Process
178
256
Holds documentation on a whole range of things on Bazaar from the
179
257
origination of ideas within the project to information on Bazaar
180
258
features and use cases. Within this directory there is a subdirectory
181
for each translation into a human language. All the documentation
259
for each translation into a human language. All the documentation
182
260
is in the ReStructuredText markup language.
185
Documentation specifically targetted at Bazaar and plugin developers.
263
Documentation specifically targeted at Bazaar and plugin developers.
186
264
(Including this document.)
190
Automatically-generated API reference information is available at
191
<http://starship.python.net/crew/mwh/bzrlibapi/>.
192
(There is an experimental editable version at
193
<http://starship.python.net/crew/mwh/bzrlibapi-oe/>.)
195
See also the `Bazaar Architectural Overview <../../developers/overview.html>`_.
268
Automatically-generated API reference information is available at
269
<http://starship.python.net/crew/mwh/bzrlibapi/>.
271
See also the `Bazaar Architectural Overview
272
<http://doc.bazaar-vcs.org/developers/overview.html>`_.
198
275
The Code Review Process
206
283
Good reviews do take time. They also regularly require a solid
207
284
understanding of the overall code base. In practice, this means a small
208
285
number of people often have a large review burden - with knowledge comes
209
responsibility. No one like their merge requests sitting in a queue going
286
responsibility. No one likes their merge requests sitting in a queue going
210
287
nowhere, so reviewing sooner rather than later is strongly encouraged.
214
Sending patches for review
215
==========================
217
If you'd like to propose a change, please post to the
218
bazaar@lists.canonical.com list with a bundle, patch, or link to a
219
branch. Put ``[PATCH]`` or ``[MERGE]`` in the subject so Bundle Buggy
220
can pick it out, and explain the change in the email message text.
221
Remember to update the NEWS file as part of your change if it makes any
222
changes visible to users or plugin developers. Please include a diff
223
against mainline if you're giving a link to a branch.
225
You can generate a merge request like this::
227
bzr send -o bug-1234.diff
229
A ``.diff`` extension is recommended instead of .bundle as many mail clients
230
will send the latter as a binary file.
232
``bzr send`` can also send mail directly if you prefer; see the help.
234
Please do **NOT** put [PATCH] or [MERGE] in the subject line if you don't
235
want it to be merged. If you want comments from developers rather than
236
to be merged, you can put ``[RFC]`` in the subject line.
238
If this change addresses a bug, please put the bug number in the subject
239
line too, in the form ``[#1]`` so that Bundle Buggy can recognize it.
241
If the change is intended for a particular release mark that in the
242
subject too, e.g. ``[1.6]``.
245
293
Review cover letters
334
382
* (your ideas here...)
337
Bundle Buggy and review outcomes
338
================================
388
From May 2009 on, we prefer people to propose code reviews through
391
* <https://launchpad.net/+tour/code-review>
393
* <https://help.launchpad.net/Code/Review>
395
Anyone can propose or comment on a merge proposal just by creating a
398
There are two ways to create a new merge proposal: through the web
399
interface or by email.
402
Proposing a merge through the web
403
---------------------------------
405
To create the proposal through the web, first push your branch to Launchpad.
406
For example, a branch dealing with documentation belonging to the Launchpad
407
User mbp could be pushed as ::
409
bzr push lp:~mbp/bzr/doc
411
Then go to the branch's web page, which in this case would be
412
<https://code.launchpad.net/~mbp/bzr/doc>. You can simplify this step by just
417
You can then click "Propose for merging into another branch", and enter your
418
cover letter (see above) into the web form. Typically you'll want to merge
419
into ``~bzr/bzr/trunk`` which will be the default; you might also want to
420
nominate merging into a release branch for a bug fix. There is the option to
421
specify a specific reviewer or type of review, and you shouldn't normally
424
Submitting the form takes you to the new page about the merge proposal
425
containing the diff of the changes, comments by interested people, and
426
controls to comment or vote on the change.
428
Proposing a merge by mail
429
-------------------------
431
To propose a merge by mail, send a bundle to ``merge@code.launchpad.net``.
433
You can generate a merge request like this::
435
bzr send -o bug-1234.diff
437
``bzr send`` can also send mail directly if you prefer; see the help.
442
From <https://code.launchpad.net/bzr/+activereviews> you can see all
443
currently active reviews, and choose one to comment on. This page also
444
shows proposals that are now approved and should be merged by someone with
448
Reviews through Bundle Buggy
449
============================
451
The Bundle Buggy tool used up to May 2009 is still available as a review
454
Sending patches for review
455
--------------------------
457
If you'd like to propose a change, please post to the
458
bazaar@lists.canonical.com list with a bundle, patch, or link to a
459
branch. Put ``[PATCH]`` or ``[MERGE]`` in the subject so Bundle Buggy
460
can pick it out, and explain the change in the email message text.
461
Remember to update the NEWS file as part of your change if it makes any
462
changes visible to users or plugin developers. Please include a diff
463
against mainline if you're giving a link to a branch.
465
You can generate a merge request like this::
467
bzr send -o bug-1234.patch
469
A ``.patch`` extension is recommended instead of .bundle as many mail clients
470
will send the latter as a binary file.
472
``bzr send`` can also send mail directly if you prefer; see the help.
474
Please do **NOT** put [PATCH] or [MERGE] in the subject line if you don't
475
want it to be merged. If you want comments from developers rather than
476
to be merged, you can put ``[RFC]`` in the subject line.
478
If this change addresses a bug, please put the bug number in the subject
479
line too, in the form ``[#1]`` so that Bundle Buggy can recognize it.
481
If the change is intended for a particular release mark that in the
482
subject too, e.g. ``[1.6]``.
340
483
Anyone can "vote" on the mailing list by expressing an opinion. Core
341
484
developers can also vote using Bundle Buggy. Here are the voting codes and
342
485
their explanations.
387
530
We use 4 space indents for blocks, and never use tab characters. (In vim,
388
531
``set expandtab``.)
533
Trailing white space should be avoided, but is allowed.
534
You should however not make lots of unrelated white space changes.
536
Unix style newlines (LF) are used.
538
Each file must have a newline at the end of it.
390
540
Lines should be no more than 79 characters if at all possible.
391
Lines that continue a long statement may be indented in either of
541
Lines that continue a long statement may be indented in either of
394
544
within the parenthesis or other character that opens the block, e.g.::
481
Functions, methods or members that are "private" to bzrlib are given
631
Functions, methods or members that are relatively private are given
482
632
a leading underscore prefix. Names without a leading underscore are
483
633
public not just across modules but to programmers using bzrlib as an
484
API. As a consequence, a leading underscore is appropriate for names
485
exposed across modules but that are not to be exposed to bzrlib API
488
636
We prefer class names to be concatenated capital words (``TestCase``)
489
637
and variables, methods and functions to be lowercase words joined by
531
679
may not catch every case but it's still useful sometimes.
685
Often when something has failed later code, including cleanups invoked
686
from ``finally`` blocks, will fail too. These secondary failures are
687
generally uninteresting compared to the original exception. So use the
688
``only_raises`` decorator (from ``bzrlib.decorators``) for methods that
689
are typically called in ``finally`` blocks, such as ``unlock`` methods.
690
For example, ``@only_raises(LockNotHeld, LockBroken)``. All errors that
691
are unlikely to be a knock-on failure from a previous failure should be
537
698
In some places we have variables which point to callables that construct
538
699
new instances. That is to say, they can be used a lot like class objects,
539
but they shouldn't be *named* like classes:
700
but they shouldn't be *named* like classes::
541
702
> I think that things named FooBar should create instances of FooBar when
542
703
> called. Its plain confusing for them to do otherwise. When we have
561
722
The ``InterObject`` provides for two-way `multiple dispatch`__: matching
562
723
up for example a source and destination repository to find the right way
563
to transfer data between them.
724
to transfer data between them.
565
726
.. __: http://en.wikipedia.org/wiki/Multiple_dispatch
567
728
There is a subclass ``InterObject`` classes for each type of object that is
568
729
dispatched this way, e.g. ``InterRepository``. Calling ``.get()`` on this
569
class will return an ``InterObject`` instance providing the best match for
730
class will return an ``InterObject`` instance providing the best match for
570
731
those parameters, and this instance then has methods for operations
571
732
between the objects.
573
736
inter = InterRepository.get(source_repo, target_repo)
574
737
inter.fetch(revision_id)
715
879
way, you need to change its name as well. For instance, if I add an optional keyword
716
880
parameter to branch.commit - that's fine. On the other hand, if I add a
717
881
keyword parameter to branch.commit which is a *required* transaction
718
object, I should rename the API - i.e. to 'branch.commit_transaction'.
882
object, I should rename the API - i.e. to 'branch.commit_transaction'.
884
(Actually, that may break code that provides a new implementation of
885
``commit`` and doesn't expect to receive the parameter.)
720
887
When renaming such supported API's, be sure to leave a deprecated_method (or
721
888
_function or ...) behind which forwards to the new API. See the
722
889
bzrlib.symbol_versioning module for decorators that take care of the
723
890
details for you - such as updating the docstring, and issuing a warning
724
when the old api is used.
891
when the old API is used.
726
893
For unsupported API's, it does not hurt to follow this discipline, but it's
727
894
not required. Minimally though, please try to rename things so that
820
987
should be only in the command-line tool.
990
Progress and Activity Indications
991
---------------------------------
993
bzrlib has a way for code to display to the user that stuff is happening
994
during a long operation. There are two particular types: *activity* which
995
means that IO is happening on a Transport, and *progress* which means that
996
higher-level application work is occurring. Both are drawn together by
999
Transport objects are responsible for calling `report_transport_activity`
1002
Progress uses a model/view pattern: application code acts on a
1003
`ProgressTask` object, which notifies the UI when it needs to be
1004
displayed. Progress tasks form a stack. To create a new progress task on
1005
top of the stack, call `bzrlib.ui.ui_factory.nested_progress_bar()`, then
1006
call `update()` on the returned ProgressTask. It can be updated with just
1007
a text description, with a numeric count, or with a numeric count and
1008
expected total count. If an expected total count is provided the view
1009
can show the progress moving along towards the expected total.
1011
The user should call `finish` on the `ProgressTask` when the logical
1012
operation has finished, so it can be removed from the stack.
1014
Progress tasks have a complex relationship with generators: it's a very
1015
good place to use them, but because python2.4 does not allow ``finally``
1016
blocks in generators it's hard to clean them up properly. In this case
1017
it's probably better to have the code calling the generator allocate a
1018
progress task for its use and then call `finalize` when it's done, which
1019
will close it if it was not already closed. The generator should also
1020
finish the progress task when it exits, because it may otherwise be a long
1021
time until the finally block runs.
1027
When filenames or similar variables are presented inline within a message,
1028
they should be enclosed in double quotes (ascii 0x22, not chiral unicode
1031
bzr: ERROR: No such file "asdf"
1033
When we print just a list of filenames there should not be any quoting:
1036
.. _bug 544297: https://bugs.launchpad.net/bugs/544297
1038
https://wiki.ubuntu.com/UnitsPolicy provides a good explanation about
1039
which unit should be used when. Roughly speaking, IEC standard applies
1040
for base-2 units and SI standard applies for base-10 units:
1042
* for network bandwidth and disk sizes, use base-10 (Mbits/s, kB/s, GB)
1044
* for RAM sizes, use base-2 (GiB, TiB)
886
1110
that exception specifically, or when it needs a substantially different
1113
#. If it is something that a caller can recover from, a custom exception
1116
#. If it is a data consistency issue, using a builtin like
1117
``ValueError``/``TypeError`` is reasonable.
1119
#. If it is a programmer error (using an api incorrectly)
1120
``AssertionError`` is reasonable.
1122
#. Otherwise, use ``BzrError`` or ``InternalBzrError``.
889
1124
Exception strings should start with a capital letter and should not have a
890
1125
final fullstop. If long, they may contain newlines to break the text.
941
1176
Within each release, entries in the news file should have the most
942
1177
user-visible changes first. So the order should be approximately:
944
* changes to existing behaviour - the highest priority because the
1179
* changes to existing behaviour - the highest priority because the
945
1180
user's existing knowledge is incorrect
946
1181
* new features - should be brought to their attention
947
1182
* bug fixes - may be of interest if the bug was affecting them, and
948
1183
should include the bug number if any
949
* major documentation changes
1184
* major documentation changes, including fixed documentation bugs
950
1185
* changes to internal interfaces
952
1187
People who made significant contributions to each change are listed in
953
1188
parenthesis. This can include reporting bugs (particularly with good
954
1189
details or reproduction recipes), submitting patches, etc.
1191
To help with merging, NEWS entries should be sorted lexicographically
1192
within each section.
997
1235
We had the problem that lots of our files were "Copyright Canonical
998
1236
Development Ltd" which is not a real company, and some other variations
999
1237
on this theme. Also, some files were missing the GPL statements.
1001
1239
I want to be clear about the intent of this patch, since copyright can
1002
1240
be a little controversial.
1004
1242
1) The big motivation for this is not to shut out the community, but
1005
1243
just to clean up all of the invalid copyright statements.
1007
1245
2) It has been the general policy for bzr that we want a single
1008
1246
copyright holder for all of the core code. This is following the model
1009
1247
set by the FSF, which makes it easier to update the code to a new
1016
1254
I'm sure Canonical would do the same).
1017
1255
As such, Canonical has requested copyright assignments from all of the
1018
1256
major contributers.
1020
1258
3) If someone wants to add code and not attribute it to Canonical, there
1021
1259
is a specific list of files that are excluded from this check. And the
1022
1260
test failure indicates where that is, and how to update it.
1024
1262
4) If anyone feels that I changed a copyright statement incorrectly, just
1025
1263
let me know, and I'll be happy to correct it. Whenever you have large
1026
1264
mechanical changes like this, it is possible to make some mistakes.
1028
1266
Just to reiterate, this is a community project, and it is meant to stay
1029
1267
that way. Core bzr code is copyright Canonical for legal reasons, and
1030
1268
the tests are just there to help us maintain that.
1042
1280
.. _pdb: http://docs.python.org/lib/debugger-commands.html
1044
If the ``BZR_PDB`` environment variable is set
1282
If the ``BZR_PDB`` environment variable is set
1045
1283
then bzr will go into pdb post-mortem mode when an unhandled exception
1048
If you send a SIGQUIT signal to bzr, which can be done by pressing
1049
Ctrl-\\ on Unix, bzr will go into the debugger immediately. You can
1050
continue execution by typing ``c``. This can be disabled if necessary
1051
by setting the environment variable ``BZR_SIGQUIT_PDB=0``.
1286
If you send a SIGQUIT or SIGBREAK signal to bzr then it will drop into the
1287
debugger immediately. SIGQUIT can be generated by pressing Ctrl-\\ on
1288
Unix. SIGBREAK is generated with Ctrl-Pause on Windows (some laptops have
1289
this as Fn-Pause). You can continue execution by typing ``c``. This can
1290
be disabled if necessary by setting the environment variable
1291
``BZR_SIGQUIT_PDB=0``.
1297
Bazaar accepts some global options starting with ``-D`` such as
1298
``-Dhpss``. These set a value in `bzrlib.debug.debug_flags`, and
1299
typically cause more information to be written to the trace file. Most
1300
`mutter` calls should be guarded by a check of those flags so that we
1301
don't write out too much information if it's not needed.
1303
Debug flags may have effects other than just emitting trace messages.
1305
Run ``bzr help global-options`` to see them all.
1307
These flags may also be set as a comma-separated list in the
1308
``debug_flags`` option in e.g. ``~/.bazaar/bazaar.conf``. (Note that it
1309
must be in this global file, not in the branch or location configuration,
1310
because it's currently only loaded at startup time.) For instance you may
1311
want to always record hpss traces and to see full error tracebacks::
1313
debug_flags = hpss, error
1085
1347
for automated processing.
1086
1348
For example: ``bzr log`` should not fail if one of the entries has text
1087
1349
that cannot be displayed.
1090
1352
Attempting to print an unprintable character will cause a UnicodeError.
1091
1353
This is for commands that are intended more as scripting support, rather
1092
1354
than plain user review.
1093
For exampl: ``bzr ls`` is designed to be used with shell scripting. One
1094
use would be ``bzr ls --null --unknows | xargs -0 rm``. If ``bzr``
1355
For example: ``bzr ls`` is designed to be used with shell scripting. One
1356
use would be ``bzr ls --null --unknowns | xargs -0 rm``. If ``bzr``
1095
1357
printed a filename with a '?', the wrong file could be deleted. (At the
1096
1358
very least, the correct file would not be deleted). An error is used to
1097
1359
indicate that the requested action could not be performed.
1100
1362
Do not attempt to automatically convert Unicode strings. This is used
1101
1363
for commands that must handle conversion themselves.
1150
1412
To create an extension, add rules to setup.py for building it with pyrex,
1151
1413
and with distutils. Now start with an empty .pyx file. At the top add
1152
"include 'yourmodule.py'". This will import the contents of foo.py into this
1414
"include 'yourmodule.py'". This will import the contents of foo.py into this
1153
1415
file at build time - remember that only one module will be loaded at
1154
1416
runtime. Now you can subclass classes, or replace functions, and only your
1155
1417
changes need to be present in the .pyx file.
1157
1419
Note that pyrex does not support all 2.4 programming idioms, so some
1158
syntax changes may be required. I.e.
1420
syntax changes may be required. I.e.
1160
- 'from foo import (bar, gam)' needs to change to not use the brackets.
1161
- 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar'
1422
- 'from foo import (bar, gam)' needs to change to not use the brackets.
1423
- 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar'
1163
1425
If the changes are too dramatic, consider
1164
1426
maintaining the python code twice - once in the .pyx, and once in the .py,
added
removed
doc/developers/HACKING.txt
