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/giveback
125
After you have pushed your branch, you will need to propose it for merging to
126
the Bazaar trunk. Go to <https://launchpad.net/your_lp_username/bzr/giveback>
127
and choose "Propose for merging into another branch". Select "~bzr/bzr/trunk"
128
to hand your changes off to the Bazaar developers for review and merging.
130
Why make a local copy of bzr.dev?
131
---------------------------------
133
Making a local mirror of bzr.dev is not strictly necessary, but it means
135
- You can use that copy of bzr.dev as your main bzr executable, and keep it
136
up-to-date using ``bzr pull``.
137
- Certain operations are faster, and can be done when offline. For example:
140
- ``bzr diff -r ancestor:...``
143
- When it's time to create your next branch, it's more convenient. When you
144
have further contributions to make, you should do them in their own branch::
147
$ bzr branch bzr.dev additional_fixes
148
$ cd additional_fixes # hack, hack, hack
82
152
Understanding the Development Process
178
248
Holds documentation on a whole range of things on Bazaar from the
179
249
origination of ideas within the project to information on Bazaar
180
250
features and use cases. Within this directory there is a subdirectory
181
for each translation into a human language. All the documentation
251
for each translation into a human language. All the documentation
182
252
is in the ReStructuredText markup language.
185
Documentation specifically targetted at Bazaar and plugin developers.
255
Documentation specifically targeted at Bazaar and plugin developers.
186
256
(Including this document.)
190
Automatically-generated API reference information is available at
191
<http://starship.python.net/crew/mwh/bzrlibapi/>.
193
See also the `Bazaar Architectural Overview <../../developers/overview.html>`_.
260
Automatically-generated API reference information is available at
261
<http://starship.python.net/crew/mwh/bzrlibapi/>.
263
See also the `Bazaar Architectural Overview
264
<http://doc.bazaar-vcs.org/developers/overview.html>`_.
196
267
The Code Review Process
204
275
Good reviews do take time. They also regularly require a solid
205
276
understanding of the overall code base. In practice, this means a small
206
277
number of people often have a large review burden - with knowledge comes
207
responsibility. No one like their merge requests sitting in a queue going
278
responsibility. No one likes their merge requests sitting in a queue going
208
279
nowhere, so reviewing sooner rather than later is strongly encouraged.
212
Sending patches for review
213
==========================
215
If you'd like to propose a change, please post to the
216
bazaar@lists.canonical.com list with a bundle, patch, or link to a
217
branch. Put ``[PATCH]`` or ``[MERGE]`` in the subject so Bundle Buggy
218
can pick it out, and explain the change in the email message text.
219
Remember to update the NEWS file as part of your change if it makes any
220
changes visible to users or plugin developers. Please include a diff
221
against mainline if you're giving a link to a branch.
223
You can generate a merge request like this::
225
bzr send -o bug-1234.patch
227
A ``.patch`` extension is recommended instead of .bundle as many mail clients
228
will send the latter as a binary file.
230
``bzr send`` can also send mail directly if you prefer; see the help.
232
Please do **NOT** put [PATCH] or [MERGE] in the subject line if you don't
233
want it to be merged. If you want comments from developers rather than
234
to be merged, you can put ``[RFC]`` in the subject line.
236
If this change addresses a bug, please put the bug number in the subject
237
line too, in the form ``[#1]`` so that Bundle Buggy can recognize it.
239
If the change is intended for a particular release mark that in the
240
subject too, e.g. ``[1.6]``.
243
285
Review cover letters
332
374
* (your ideas here...)
335
Bundle Buggy and review outcomes
336
================================
380
From May 2009 on, we prefer people to propose code reviews through
383
* <https://launchpad.net/+tour/code-review>
385
* <https://help.launchpad.net/Code/Review>
387
Anyone can propose or comment on a merge proposal just by creating a
390
There are two ways to create a new merge proposal: through the web
391
interface or by email.
394
Proposing a merge through the web
395
---------------------------------
397
To create the proposal through the web, first push your branch to Launchpad.
398
For example, a branch dealing with documentation belonging to the Launchpad
399
User mbp could be pushed as ::
401
bzr push lp:~mbp/bzr/doc
403
Then go to the branch's web page, which in this case would be
404
<https://code.launchpad.net/~mbp/bzr/doc>. You can simplify this step by just
409
You can then click "Propose for merging into another branch", and enter your
410
cover letter (see above) into the web form. Typically you'll want to merge
411
into ``~bzr/bzr/trunk`` which will be the default; you might also want to
412
nominate merging into a release branch for a bug fix. There is the option to
413
specify a specific reviewer or type of review, and you shouldn't normally
416
Submitting the form takes you to the new page about the merge proposal
417
containing the diff of the changes, comments by interested people, and
418
controls to comment or vote on the change.
420
Proposing a merge by mail
421
-------------------------
423
To propose a merge by mail, send a bundle to ``merge@code.launchpad.net``.
425
You can generate a merge request like this::
427
bzr send -o bug-1234.diff
429
``bzr send`` can also send mail directly if you prefer; see the help.
434
From <https://code.launchpad.net/bzr/+activereviews> you can see all
435
currently active reviews, and choose one to comment on. This page also
436
shows proposals that are now approved and should be merged by someone with
440
Reviews through Bundle Buggy
441
============================
443
The Bundle Buggy tool used up to May 2009 is still available as a review
446
Sending patches for review
447
--------------------------
449
If you'd like to propose a change, please post to the
450
bazaar@lists.canonical.com list with a bundle, patch, or link to a
451
branch. Put ``[PATCH]`` or ``[MERGE]`` in the subject so Bundle Buggy
452
can pick it out, and explain the change in the email message text.
453
Remember to update the NEWS file as part of your change if it makes any
454
changes visible to users or plugin developers. Please include a diff
455
against mainline if you're giving a link to a branch.
457
You can generate a merge request like this::
459
bzr send -o bug-1234.patch
461
A ``.patch`` extension is recommended instead of .bundle as many mail clients
462
will send the latter as a binary file.
464
``bzr send`` can also send mail directly if you prefer; see the help.
466
Please do **NOT** put [PATCH] or [MERGE] in the subject line if you don't
467
want it to be merged. If you want comments from developers rather than
468
to be merged, you can put ``[RFC]`` in the subject line.
470
If this change addresses a bug, please put the bug number in the subject
471
line too, in the form ``[#1]`` so that Bundle Buggy can recognize it.
473
If the change is intended for a particular release mark that in the
474
subject too, e.g. ``[1.6]``.
338
475
Anyone can "vote" on the mailing list by expressing an opinion. Core
339
476
developers can also vote using Bundle Buggy. Here are the voting codes and
340
477
their explanations.
385
522
We use 4 space indents for blocks, and never use tab characters. (In vim,
386
523
``set expandtab``.)
388
No trailing white space is allowed.
525
Trailing white space should be avoided, but is allowed.
526
You should however not make lots of unrelated white space changes.
390
528
Unix style newlines (LF) are used.
392
530
Each file must have a newline at the end of it.
394
532
Lines should be no more than 79 characters if at all possible.
395
Lines that continue a long statement may be indented in either of
533
Lines that continue a long statement may be indented in either of
398
536
within the parenthesis or other character that opens the block, e.g.::
485
Functions, methods or members that are "private" to bzrlib are given
623
Functions, methods or members that are relatively private are given
486
624
a leading underscore prefix. Names without a leading underscore are
487
625
public not just across modules but to programmers using bzrlib as an
488
API. As a consequence, a leading underscore is appropriate for names
489
exposed across modules but that are not to be exposed to bzrlib API
492
628
We prefer class names to be concatenated capital words (``TestCase``)
493
629
and variables, methods and functions to be lowercase words joined by
535
671
may not catch every case but it's still useful sometimes.
677
Often when something has failed later code, including cleanups invoked
678
from ``finally`` blocks, will fail too. These secondary failures are
679
generally uninteresting compared to the original exception. So use the
680
``only_raises`` decorator (from ``bzrlib.decorators``) for methods that
681
are typically called in ``finally`` blocks, such as ``unlock`` methods.
682
For example, ``@only_raises(LockNotHeld, LockBroken)``. All errors that
683
are unlikely to be a knock-on failure from a previous failure should be
565
714
The ``InterObject`` provides for two-way `multiple dispatch`__: matching
566
715
up for example a source and destination repository to find the right way
567
to transfer data between them.
716
to transfer data between them.
569
718
.. __: http://en.wikipedia.org/wiki/Multiple_dispatch
571
720
There is a subclass ``InterObject`` classes for each type of object that is
572
721
dispatched this way, e.g. ``InterRepository``. Calling ``.get()`` on this
573
class will return an ``InterObject`` instance providing the best match for
722
class will return an ``InterObject`` instance providing the best match for
574
723
those parameters, and this instance then has methods for operations
575
724
between the objects.
719
869
way, you need to change its name as well. For instance, if I add an optional keyword
720
870
parameter to branch.commit - that's fine. On the other hand, if I add a
721
871
keyword parameter to branch.commit which is a *required* transaction
722
object, I should rename the API - i.e. to 'branch.commit_transaction'.
872
object, I should rename the API - i.e. to 'branch.commit_transaction'.
874
(Actually, that may break code that provides a new implementation of
875
``commit`` and doesn't expect to receive the parameter.)
724
877
When renaming such supported API's, be sure to leave a deprecated_method (or
725
878
_function or ...) behind which forwards to the new API. See the
726
879
bzrlib.symbol_versioning module for decorators that take care of the
727
880
details for you - such as updating the docstring, and issuing a warning
728
when the old api is used.
881
when the old API is used.
730
883
For unsupported API's, it does not hurt to follow this discipline, but it's
731
884
not required. Minimally though, please try to rename things so that
989
1142
Within each release, entries in the news file should have the most
990
1143
user-visible changes first. So the order should be approximately:
992
* changes to existing behaviour - the highest priority because the
1145
* changes to existing behaviour - the highest priority because the
993
1146
user's existing knowledge is incorrect
994
1147
* new features - should be brought to their attention
995
1148
* bug fixes - may be of interest if the bug was affecting them, and
996
1149
should include the bug number if any
997
* major documentation changes
1150
* major documentation changes, including fixed documentation bugs
998
1151
* changes to internal interfaces
1000
1153
People who made significant contributions to each change are listed in
1001
1154
parenthesis. This can include reporting bugs (particularly with good
1002
1155
details or reproduction recipes), submitting patches, etc.
1157
To help with merging, NEWS entries should be sorted lexicographically
1158
within each section.
1045
1201
We had the problem that lots of our files were "Copyright Canonical
1046
1202
Development Ltd" which is not a real company, and some other variations
1047
1203
on this theme. Also, some files were missing the GPL statements.
1049
1205
I want to be clear about the intent of this patch, since copyright can
1050
1206
be a little controversial.
1052
1208
1) The big motivation for this is not to shut out the community, but
1053
1209
just to clean up all of the invalid copyright statements.
1055
1211
2) It has been the general policy for bzr that we want a single
1056
1212
copyright holder for all of the core code. This is following the model
1057
1213
set by the FSF, which makes it easier to update the code to a new
1064
1220
I'm sure Canonical would do the same).
1065
1221
As such, Canonical has requested copyright assignments from all of the
1066
1222
major contributers.
1068
1224
3) If someone wants to add code and not attribute it to Canonical, there
1069
1225
is a specific list of files that are excluded from this check. And the
1070
1226
test failure indicates where that is, and how to update it.
1072
1228
4) If anyone feels that I changed a copyright statement incorrectly, just
1073
1229
let me know, and I'll be happy to correct it. Whenever you have large
1074
1230
mechanical changes like this, it is possible to make some mistakes.
1076
1232
Just to reiterate, this is a community project, and it is meant to stay
1077
1233
that way. Core bzr code is copyright Canonical for legal reasons, and
1078
1234
the tests are just there to help us maintain that.
1090
1246
.. _pdb: http://docs.python.org/lib/debugger-commands.html
1092
If the ``BZR_PDB`` environment variable is set
1248
If the ``BZR_PDB`` environment variable is set
1093
1249
then bzr will go into pdb post-mortem mode when an unhandled exception
1096
If you send a SIGQUIT signal to bzr, which can be done by pressing
1097
Ctrl-\\ on Unix, bzr will go into the debugger immediately. You can
1098
continue execution by typing ``c``. This can be disabled if necessary
1099
by setting the environment variable ``BZR_SIGQUIT_PDB=0``.
1252
If you send a SIGQUIT or SIGBREAK signal to bzr then it will drop into the
1253
debugger immediately. SIGQUIT can be generated by pressing Ctrl-\\ on
1254
Unix. SIGBREAK is generated with Ctrl-Pause on Windows (some laptops have
1255
this as Fn-Pause). You can continue execution by typing ``c``. This can
1256
be disabled if necessary by setting the environment variable
1257
``BZR_SIGQUIT_PDB=0``.
1155
1313
for automated processing.
1156
1314
For example: ``bzr log`` should not fail if one of the entries has text
1157
1315
that cannot be displayed.
1160
1318
Attempting to print an unprintable character will cause a UnicodeError.
1161
1319
This is for commands that are intended more as scripting support, rather
1162
1320
than plain user review.
1163
For exampl: ``bzr ls`` is designed to be used with shell scripting. One
1164
use would be ``bzr ls --null --unknows | xargs -0 rm``. If ``bzr``
1321
For example: ``bzr ls`` is designed to be used with shell scripting. One
1322
use would be ``bzr ls --null --unknowns | xargs -0 rm``. If ``bzr``
1165
1323
printed a filename with a '?', the wrong file could be deleted. (At the
1166
1324
very least, the correct file would not be deleted). An error is used to
1167
1325
indicate that the requested action could not be performed.
1170
1328
Do not attempt to automatically convert Unicode strings. This is used
1171
1329
for commands that must handle conversion themselves.
1220
1378
To create an extension, add rules to setup.py for building it with pyrex,
1221
1379
and with distutils. Now start with an empty .pyx file. At the top add
1222
"include 'yourmodule.py'". This will import the contents of foo.py into this
1380
"include 'yourmodule.py'". This will import the contents of foo.py into this
1223
1381
file at build time - remember that only one module will be loaded at
1224
1382
runtime. Now you can subclass classes, or replace functions, and only your
1225
1383
changes need to be present in the .pyx file.
1227
1385
Note that pyrex does not support all 2.4 programming idioms, so some
1228
syntax changes may be required. I.e.
1386
syntax changes may be required. I.e.
1230
- 'from foo import (bar, gam)' needs to change to not use the brackets.
1231
- 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar'
1388
- 'from foo import (bar, gam)' needs to change to not use the brackets.
1389
- 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar'
1233
1391
If the changes are too dramatic, consider
1234
1392
maintaining the python code twice - once in the .pyx, and once in the .py,
added
removed
doc/developers/HACKING.txt
