11
11
the Bazaar mailing list. To propose a correction or addition to this
12
12
document, send a merge request or new text to the mailing list.
14
The current version of this document is available in the file
15
``doc/en/developer-guide/HACKING.txt`` in the source tree, or at
16
http://doc.bazaar-vcs.org/bzr.dev/en/developer-guide/HACKING.html
19
`Bazaar Developer Documentation Catalog <../../developers/index.html>`_.
14
The latest developer documentation can be found online at
15
http://doc.bazaar-vcs.org/developers/.
68
62
to involving the community before you spend much time on a change.
71
* you get to build on the wisdom on others, saving time
65
* you get to build on the wisdom of others, saving time
73
* if others can direct you to similar code, it minimises the work to be done
67
* if others can direct you to similar code, it minimises the work to be done
75
69
* it assists everyone in coordinating direction, priorities and effort.
82
76
Bazaar Development in a Nutshell
83
77
================================
85
Looking for a 10 minute introduction to submitting a change?
86
See http://bazaar-vcs.org/BzrGivingBack.
88
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
91
160
Understanding the Development Process
187
256
Holds documentation on a whole range of things on Bazaar from the
188
257
origination of ideas within the project to information on Bazaar
189
258
features and use cases. Within this directory there is a subdirectory
190
for each translation into a human language. All the documentation
259
for each translation into a human language. All the documentation
191
260
is in the ReStructuredText markup language.
194
Documentation specifically targetted at Bazaar and plugin developers.
263
Documentation specifically targeted at Bazaar and plugin developers.
195
264
(Including this document.)
199
Automatically-generated API reference information is available at
200
<http://starship.python.net/crew/mwh/bzrlibapi/>.
202
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>`_.
205
275
The Code Review Process
332
402
Proposing a merge through the web
333
403
---------------------------------
335
To create the propsal through the web: push your branch to Launchpad, eg::
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 ::
337
409
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
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
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.
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
352
424
Submitting the form takes you to the new page about the merge proposal
353
425
containing the diff of the changes, comments by interested people, and
559
Functions, methods or members that are "private" to bzrlib are given
631
Functions, methods or members that are relatively private are given
560
632
a leading underscore prefix. Names without a leading underscore are
561
633
public not just across modules but to programmers using bzrlib as an
562
API. As a consequence, a leading underscore is appropriate for names
563
exposed across modules but that are not to be exposed to bzrlib API
566
636
We prefer class names to be concatenated capital words (``TestCase``)
567
637
and variables, methods and functions to be lowercase words joined by
609
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
615
698
In some places we have variables which point to callables that construct
616
699
new instances. That is to say, they can be used a lot like class objects,
617
but they shouldn't be *named* like classes:
700
but they shouldn't be *named* like classes::
619
702
> I think that things named FooBar should create instances of FooBar when
620
703
> called. Its plain confusing for them to do otherwise. When we have
639
722
The ``InterObject`` provides for two-way `multiple dispatch`__: matching
640
723
up for example a source and destination repository to find the right way
641
to transfer data between them.
724
to transfer data between them.
643
726
.. __: http://en.wikipedia.org/wiki/Multiple_dispatch
645
728
There is a subclass ``InterObject`` classes for each type of object that is
646
729
dispatched this way, e.g. ``InterRepository``. Calling ``.get()`` on this
647
class will return an ``InterObject`` instance providing the best match for
730
class will return an ``InterObject`` instance providing the best match for
648
731
those parameters, and this instance then has methods for operations
649
732
between the objects.
651
736
inter = InterRepository.get(source_repo, target_repo)
652
737
inter.fetch(revision_id)
782
868
Evolving Interfaces
783
869
===================
785
We have a commitment to 6 months API stability - any supported symbol in a
786
release of bzr MUST NOT be altered in any way that would result in
871
We don't change APIs in stable branches: any supported symbol in a stable
872
release of bzr must not be altered in any way that would result in
787
873
breaking existing code that uses it. That means that method names,
788
874
parameter ordering, parameter names, variable and attribute names etc must
789
875
not be changed without leaving a 'deprecated forwarder' behind. This even
793
879
way, you need to change its name as well. For instance, if I add an optional keyword
794
880
parameter to branch.commit - that's fine. On the other hand, if I add a
795
881
keyword parameter to branch.commit which is a *required* transaction
796
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.)
798
887
When renaming such supported API's, be sure to leave a deprecated_method (or
799
888
_function or ...) behind which forwards to the new API. See the
800
889
bzrlib.symbol_versioning module for decorators that take care of the
801
890
details for you - such as updating the docstring, and issuing a warning
802
when the old api is used.
891
when the old API is used.
804
893
For unsupported API's, it does not hurt to follow this discipline, but it's
805
894
not required. Minimally though, please try to rename things so that
932
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)
1000
1114
#. If it is something that a caller can recover from, a custom exception
1003
1117
#. If it is a data consistency issue, using a builtin like
1004
``ValueError``/``TypeError`` is reasonable.
1118
``ValueError``/``TypeError`` is reasonable.
1006
1120
#. If it is a programmer error (using an api incorrectly)
1007
``AssertionError`` is reasonable.
1121
``AssertionError`` is reasonable.
1009
1123
#. Otherwise, use ``BzrError`` or ``InternalBzrError``.
1063
1177
Within each release, entries in the news file should have the most
1064
1178
user-visible changes first. So the order should be approximately:
1066
* changes to existing behaviour - the highest priority because the
1180
* changes to existing behaviour - the highest priority because the
1067
1181
user's existing knowledge is incorrect
1068
1182
* new features - should be brought to their attention
1069
1183
* bug fixes - may be of interest if the bug was affecting them, and
1070
1184
should include the bug number if any
1071
* major documentation changes
1185
* major documentation changes, including fixed documentation bugs
1072
1186
* changes to internal interfaces
1074
1188
People who made significant contributions to each change are listed in
1075
1189
parenthesis. This can include reporting bugs (particularly with good
1076
1190
details or reproduction recipes), submitting patches, etc.
1192
To help with merging, NEWS entries should be sorted lexicographically
1193
within each section.
1119
1236
We had the problem that lots of our files were "Copyright Canonical
1120
1237
Development Ltd" which is not a real company, and some other variations
1121
1238
on this theme. Also, some files were missing the GPL statements.
1123
1240
I want to be clear about the intent of this patch, since copyright can
1124
1241
be a little controversial.
1126
1243
1) The big motivation for this is not to shut out the community, but
1127
1244
just to clean up all of the invalid copyright statements.
1129
1246
2) It has been the general policy for bzr that we want a single
1130
1247
copyright holder for all of the core code. This is following the model
1131
1248
set by the FSF, which makes it easier to update the code to a new
1138
1255
I'm sure Canonical would do the same).
1139
1256
As such, Canonical has requested copyright assignments from all of the
1140
1257
major contributers.
1142
1259
3) If someone wants to add code and not attribute it to Canonical, there
1143
1260
is a specific list of files that are excluded from this check. And the
1144
1261
test failure indicates where that is, and how to update it.
1146
1263
4) If anyone feels that I changed a copyright statement incorrectly, just
1147
1264
let me know, and I'll be happy to correct it. Whenever you have large
1148
1265
mechanical changes like this, it is possible to make some mistakes.
1150
1267
Just to reiterate, this is a community project, and it is meant to stay
1151
1268
that way. Core bzr code is copyright Canonical for legal reasons, and
1152
1269
the tests are just there to help us maintain that.
1164
1281
.. _pdb: http://docs.python.org/lib/debugger-commands.html
1166
If the ``BZR_PDB`` environment variable is set
1283
If the ``BZR_PDB`` environment variable is set
1167
1284
then bzr will go into pdb post-mortem mode when an unhandled exception
1170
If you send a SIGQUIT signal to bzr, which can be done by pressing
1171
Ctrl-\\ on Unix, bzr will go into the debugger immediately. You can
1172
continue execution by typing ``c``. This can be disabled if necessary
1173
by setting the environment variable ``BZR_SIGQUIT_PDB=0``.
1287
If you send a SIGQUIT or SIGBREAK signal to bzr then it will drop into the
1288
debugger immediately. SIGQUIT can be generated by pressing Ctrl-\\ on
1289
Unix. SIGBREAK is generated with Ctrl-Pause on Windows (some laptops have
1290
this as Fn-Pause). You can continue execution by typing ``c``. This can
1291
be disabled if necessary by setting the environment variable
1292
``BZR_SIGQUIT_PDB=0``.
1229
1348
for automated processing.
1230
1349
For example: ``bzr log`` should not fail if one of the entries has text
1231
1350
that cannot be displayed.
1234
1353
Attempting to print an unprintable character will cause a UnicodeError.
1235
1354
This is for commands that are intended more as scripting support, rather
1236
1355
than plain user review.
1237
For exampl: ``bzr ls`` is designed to be used with shell scripting. One
1238
use would be ``bzr ls --null --unknows | xargs -0 rm``. If ``bzr``
1356
For example: ``bzr ls`` is designed to be used with shell scripting. One
1357
use would be ``bzr ls --null --unknowns | xargs -0 rm``. If ``bzr``
1239
1358
printed a filename with a '?', the wrong file could be deleted. (At the
1240
1359
very least, the correct file would not be deleted). An error is used to
1241
1360
indicate that the requested action could not be performed.
1244
1363
Do not attempt to automatically convert Unicode strings. This is used
1245
1364
for commands that must handle conversion themselves.
1294
1413
To create an extension, add rules to setup.py for building it with pyrex,
1295
1414
and with distutils. Now start with an empty .pyx file. At the top add
1296
"include 'yourmodule.py'". This will import the contents of foo.py into this
1415
"include 'yourmodule.py'". This will import the contents of foo.py into this
1297
1416
file at build time - remember that only one module will be loaded at
1298
1417
runtime. Now you can subclass classes, or replace functions, and only your
1299
1418
changes need to be present in the .pyx file.
1301
1420
Note that pyrex does not support all 2.4 programming idioms, so some
1302
syntax changes may be required. I.e.
1421
syntax changes may be required. I.e.
1304
- 'from foo import (bar, gam)' needs to change to not use the brackets.
1305
- 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar'
1423
- 'from foo import (bar, gam)' needs to change to not use the brackets.
1424
- 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar'
1307
1426
If the changes are too dramatic, consider
1308
1427
maintaining the python code twice - once in the .pyx, and once in the .py,
1540
1659
https://blueprints.launchpad.net/bzr/. Once a blueprint for ready for
1541
1660
review, please announce it on the mailing list.
1543
Alternatively, send an email begining with [RFC] with the proposal to the
1662
Alternatively, send an email beginning with [RFC] with the proposal to the
1544
1663
list. In some cases, you may wish to attach proposed code or a proposed
1545
1664
developer document if that best communicates the idea. Debate can then
1546
1665
proceed using the normal merge review processes.
added
removed
doc/developers/HACKING.txt
