46
46
If nothing else, perhaps you'll find inspiration in how other developers
47
47
have solved their challenges.
49
Finding Something To Do
50
=======================
52
Ad-hoc performance work can also be done. One useful tool is the 'evil' debug
53
flag. For instance running ``bzr -Devil commit -m "test"`` will log a backtrace
54
to the bzr log file for every method call which triggers a slow or non-scalable
55
part of the bzr library. So checking that a given command with ``-Devil`` has
56
no backtraces logged to the log file is a good way to find problem function
57
calls that might be nested deep in the code base.
59
50
Planning and Discussing Changes
60
51
===============================
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.patch
229
A ``.patch`` 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]``.
223
245
Review cover letters
312
334
* (your ideas here...)
318
From May 2009 on, we prefer people to propose code reviews through
321
* <https://launchpad.net/+tour/code-review>
323
* <https://help.launchpad.net/Code/Review>
325
Anyone can propose or comment on a merge propsal just by creating a
328
There are two ways to create a new merge proposal: through the web
329
interface or by email.
332
Proposing a merge through the web
333
---------------------------------
335
To create the propsal through the web: push your branch to Launchpad, eg::
337
bzr push lp:~mbp/bzr/doc
339
then go to the branch's web page, which in this case would be
340
<https://code.launchpad.net/~mbp/bzr/doc>. You can automate that by just
345
You can then click "Propose for merging into another branch", and enter a
346
cover letter into the web form. Typically you'll want to merge into
347
``~bzr/bzr/trunk`` which will be the default; you might also want to
348
nominate merging into a release branch for a bug fix. There is the option
349
to specify a specific reviewer or type of review, and you shouldn't
350
normally change those.
352
Submitting the form takes you to the new page about the merge proposal
353
containing the diff of the changes, comments by interested people, and
354
controls to comment or vote on the change.
356
Proposing a merge by mail
357
-------------------------
359
To propose a merge by mail, send a bundle to ``merge@code.launchpad.net``.
361
You can generate a merge request like this::
363
bzr send -o bug-1234.diff
365
``bzr send`` can also send mail directly if you prefer; see the help.
370
From <https://code.launchpad.net/bzr/+activereviews> you can see all
371
currently active reviews, and choose one to comment on. This page also
372
shows proposals that are now approved and should be merged by someone with
376
Reviews through Bundle Buggy
377
============================
379
The Bundle Buggy tool used up to May 2009 is still available as a review
382
Sending patches for review
383
--------------------------
385
If you'd like to propose a change, please post to the
386
bazaar@lists.canonical.com list with a bundle, patch, or link to a
387
branch. Put ``[PATCH]`` or ``[MERGE]`` in the subject so Bundle Buggy
388
can pick it out, and explain the change in the email message text.
389
Remember to update the NEWS file as part of your change if it makes any
390
changes visible to users or plugin developers. Please include a diff
391
against mainline if you're giving a link to a branch.
393
You can generate a merge request like this::
395
bzr send -o bug-1234.patch
397
A ``.patch`` extension is recommended instead of .bundle as many mail clients
398
will send the latter as a binary file.
400
``bzr send`` can also send mail directly if you prefer; see the help.
402
Please do **NOT** put [PATCH] or [MERGE] in the subject line if you don't
403
want it to be merged. If you want comments from developers rather than
404
to be merged, you can put ``[RFC]`` in the subject line.
406
If this change addresses a bug, please put the bug number in the subject
407
line too, in the form ``[#1]`` so that Bundle Buggy can recognize it.
409
If the change is intended for a particular release mark that in the
410
subject too, e.g. ``[1.6]``.
337
Bundle Buggy and review outcomes
338
================================
411
340
Anyone can "vote" on the mailing list by expressing an opinion. Core
412
341
developers can also vote using Bundle Buggy. Here are the voting codes and
413
342
their explanations.
898
820
should be only in the command-line tool.
901
Progress and Activity Indications
902
---------------------------------
904
bzrlib has a way for code to display to the user that stuff is happening
905
during a long operation. There are two particular types: *activity* which
906
means that IO is happening on a Transport, and *progress* which means that
907
higher-level application work is occurring. Both are drawn together by
910
Transport objects are responsible for calling `report_transport_activity`
913
Progress uses a model/view pattern: application code acts on a
914
`ProgressTask` object, which notifies the UI when it needs to be
915
displayed. Progress tasks form a stack. To create a new progress task on
916
top of the stack, call `bzrlib.ui.ui_factory.nested_progress_bar()`, then
917
call `update()` on the returned ProgressTask. It can be updated with just
918
a text description, with a numeric count, or with a numeric count and
919
expected total count. If an expected total count is provided the view
920
can show the progress moving along towards the expected total.
922
The user should call `finish` on the `ProgressTask` when the logical
923
operation has finished, so it can be removed from the stack.
925
Progress tasks have a complex relatioship with generators: it's a very
926
good place to use them, but because python2.4 does not allow ``finally``
927
blocks in generators it's hard to clean them up properly. In this case
928
it's probably better to have the code calling the generator allocate a
929
progress task for its use and then call `finalize` when it's done, which
930
will close it if it was not already closed. The generator should also
931
finish the progress task when it exits, because it may otherwise be a long
932
time until the finally block runs.
997
886
that exception specifically, or when it needs a substantially different
1000
#. If it is something that a caller can recover from, a custom exception
1003
#. If it is a data consistency issue, using a builtin like
1004
``ValueError``/``TypeError`` is reasonable.
1006
#. If it is a programmer error (using an api incorrectly)
1007
``AssertionError`` is reasonable.
1009
#. Otherwise, use ``BzrError`` or ``InternalBzrError``.
1011
889
Exception strings should start with a capital letter and should not have a
1012
890
final fullstop. If long, they may contain newlines to break the text.
1173
1051
by setting the environment variable ``BZR_SIGQUIT_PDB=0``.
1179
Bazaar accepts some global options starting with ``-D`` such as
1180
``-Dhpss``. These set a value in `bzrlib.debug.debug_flags`, and
1181
typically cause more information to be written to the trace file. Most
1182
`mutter` calls should be guarded by a check of those flags so that we
1183
don't write out too much information if it's not needed.
1185
Debug flags may have effects other than just emitting trace messages.
1187
Run ``bzr help global-options`` to see them all.
1189
These flags may also be set as a comma-separated list in the
1190
``debug_flags`` option in e.g. ``~/.bazaar/bazaar.conf``. (Note that it
1191
must be in this global file, not in the branch or location configuration,
1192
because it's currently only loaded at startup time.) For instance you may
1193
want to always record hpss traces and to see full error tracebacks::
1195
debug_flags = hpss, error
added
removed
doc/developers/HACKING.txt
