212
215
Navigating the Code Base
213
216
========================
215
TODO: List and describe in one line the purpose of each directory
216
inside an installation of bzr.
218
TODO: Refer to a central location holding an up to date copy of the API
219
documentation generated by epydoc, e.g. something like
220
http://starship.python.net/crew/mwh/bzrlibapi/bzrlib.html.
218
.. Was at <http://bazaar-vcs.org/NewDeveloperIntroduction>
220
Some of the key files in this directory are:
223
The command you run to start Bazaar itself. This script is pretty
224
short and just does some checks then jumps into bzrlib.
227
This file covers a brief introduction to Bazaar and lists some of its
231
Summary of changes in each Bazaar release that can affect users or
235
Installs Bazaar system-wide or to your home directory. To perform
236
development work on Bazaar it is not required to run this file - you
237
can simply run the bzr command from the top level directory of your
238
development copy. Note: That if you run setup.py this will create a
239
'build' directory in your development branch. There's nothing wrong
240
with this but don't be confused by it. The build process puts a copy
241
of the main code base into this build directory, along with some other
242
files. You don't need to go in here for anything discussed in this
246
Possibly the most exciting folder of all, bzrlib holds the main code
247
base. This is where you will go to edit python files and contribute to
251
Holds documentation on a whole range of things on Bazaar from the
252
origination of ideas within the project to information on Bazaar
253
features and use cases. Within this directory there is a subdirectory
254
for each translation into a human language. All the documentation
255
is in the ReStructuredText markup language.
258
Documentation specifically targetted at Bazaar and plugin developers.
259
(Including this document.)
263
Automatically-generated API reference information is available at
264
<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.
283
331
This option can be combined with other selftest options (like -x) and
284
332
filter patterns to understand their effect.
334
Once you understand how to create a list of tests, you can use the --load-list
335
option to run only a restricted set of tests that you kept in a file, one test
336
id by line. Keep in mind that this will never be sufficient to validate your
337
modifications, you still need to run the full test suite for that, but using it
338
can help in some cases (like running only the failed tests for some time)::
340
./bzr selftest -- load-list my_failing_tests
342
This option can also be combined with other selftest options, including
343
patterns. It has some drawbacks though, the list can become out of date pretty
344
quick when doing Test Driven Development.
346
To address this concern, there is another way to run a restricted set of tests:
347
the --starting-with option will run only the tests whose name starts with the
348
specified string. It will also avoid loading the other tests and as a
349
consequence starts running your tests quicker::
351
./bzr selftest --starting-with bzrlib.blackbox
353
This option can be combined with all the other selftest options including
354
--load-list. The later is rarely used but allows to run a subset of a list of
355
failing tests for example.
287
357
Test suite debug flags
288
358
----------------------
628
698
the form of URL components.
637
We have a commitment to 6 months API stability - any supported symbol in a
638
release of bzr MUST NOT be altered in any way that would result in
639
breaking existing code that uses it. That means that method names,
640
parameter ordering, parameter names, variable and attribute names etc must
641
not be changed without leaving a 'deprecated forwarder' behind. This even
642
applies to modules and classes.
644
If you wish to change the behaviour of a supported API in an incompatible
645
way, you need to change its name as well. For instance, if I add an optional keyword
646
parameter to branch.commit - that's fine. On the other hand, if I add a
647
keyword parameter to branch.commit which is a *required* transaction
648
object, I should rename the API - i.e. to 'branch.commit_transaction'.
650
When renaming such supported API's, be sure to leave a deprecated_method (or
651
_function or ...) behind which forwards to the new API. See the
652
bzrlib.symbol_versioning module for decorators that take care of the
653
details for you - such as updating the docstring, and issuing a warning
654
when the old api is used.
656
For unsupported API's, it does not hurt to follow this discipline, but it's
657
not required. Minimally though, please try to rename things so that
658
callers will at least get an AttributeError rather than weird results.
661
Deprecation decorators
662
----------------------
664
``bzrlib.symbol_versioning`` provides decorators that can be attached to
665
methods, functions, and other interfaces to indicate that they should no
668
To deprecate a static method you must call ``deprecated_function``
669
(**not** method), after the staticmethod call::
672
@deprecated_function(zero_ninetyone)
673
def create_repository(base, shared=False, format=None):
675
When you deprecate an API, you should not just delete its tests, because
676
then we might introduce bugs in them. If the API is still present at all,
677
it should still work. The basic approach is to use
678
``TestCase.applyDeprecated`` which in one step checks that the API gives
679
the expected deprecation message, and also returns the real result from
680
the method, so that tests can keep running.
682
701
Coding Style Guidelines
683
=======================
702
#######################
685
704
hasattr and getattr
688
707
``hasattr`` should not be used because it swallows exceptions including
689
708
``KeyboardInterrupt``. Instead, say something like ::
943
956
being phased out.
959
Object string representations
960
=============================
962
Python prints objects using their ``__repr__`` method when they are
963
written to logs, exception tracebacks, or the debugger. We want
964
objects to have useful representations to help in determining what went
967
If you add a new class you should generally add a ``__repr__`` method
968
unless there is an adequate method in a parent class. There should be a
971
Representations should typically look like Python constructor syntax, but
972
they don't need to include every value in the object and they don't need
973
to be able to actually execute. They're to be read by humans, not
974
machines. Don't hardcode the classname in the format, so that we get the
975
correct value if the method is inherited by a subclass. If you're
976
printing attributes of the object, including strings, you should normally
977
use ``%r`` syntax (to call their repr in turn).
979
Try to avoid the representation becoming more than one or two lines long.
980
(But balance this against including useful information, and simplicity of
983
Because repr methods are often called when something has already gone
984
wrong, they should be written somewhat more defensively than most code.
985
The object may be half-initialized or in some other way in an illegal
986
state. The repr method shouldn't raise an exception, or it may hide the
987
(probably more useful) underlying exception.
992
return '%s(%r)' % (self.__class__.__name__,
999
A bare ``except`` statement will catch all exceptions, including ones that
1000
really should terminate the program such as ``MemoryError`` and
1001
``KeyboardInterrupt``. They should rarely be used unless the exception is
1002
later re-raised. Even then, think about whether catching just
1003
``Exception`` (which excludes system errors in Python2.5 and later) would
1014
We have a commitment to 6 months API stability - any supported symbol in a
1015
release of bzr MUST NOT be altered in any way that would result in
1016
breaking existing code that uses it. That means that method names,
1017
parameter ordering, parameter names, variable and attribute names etc must
1018
not be changed without leaving a 'deprecated forwarder' behind. This even
1019
applies to modules and classes.
1021
If you wish to change the behaviour of a supported API in an incompatible
1022
way, you need to change its name as well. For instance, if I add an optional keyword
1023
parameter to branch.commit - that's fine. On the other hand, if I add a
1024
keyword parameter to branch.commit which is a *required* transaction
1025
object, I should rename the API - i.e. to 'branch.commit_transaction'.
1027
When renaming such supported API's, be sure to leave a deprecated_method (or
1028
_function or ...) behind which forwards to the new API. See the
1029
bzrlib.symbol_versioning module for decorators that take care of the
1030
details for you - such as updating the docstring, and issuing a warning
1031
when the old api is used.
1033
For unsupported API's, it does not hurt to follow this discipline, but it's
1034
not required. Minimally though, please try to rename things so that
1035
callers will at least get an AttributeError rather than weird results.
1038
Deprecation decorators
1039
----------------------
1041
``bzrlib.symbol_versioning`` provides decorators that can be attached to
1042
methods, functions, and other interfaces to indicate that they should no
1043
longer be used. For example::
1045
@deprecated_method(deprecated_in((0, 1, 4)))
1047
return self._new_foo()
1049
To deprecate a static method you must call ``deprecated_function``
1050
(**not** method), after the staticmethod call::
1053
@deprecated_function(deprecated_in((0, 1, 4)))
1054
def create_repository(base, shared=False, format=None):
1056
When you deprecate an API, you should not just delete its tests, because
1057
then we might introduce bugs in them. If the API is still present at all,
1058
it should still work. The basic approach is to use
1059
``TestCase.applyDeprecated`` which in one step checks that the API gives
1060
the expected deprecation message, and also returns the real result from
1061
the method, so that tests can keep running.
1063
Deprecation warnings will be suppressed for final releases, but not for
1064
development versions or release candidates, or when running ``bzr
1065
selftest``. This gives developers information about whether their code is
1066
using deprecated functions, but avoids confusing users about things they
1494
1618
differences between core and non-core contributors to a minimum.
1497
The Development Lifecycle
1498
-------------------------
1500
As a rule, Bazaar development follows a 4 week cycle:
1502
* 2 weeks - general changes
1503
* 1 week - feature freeze
1504
* 1 week+ - Release Candidate stabilization
1506
During the FeatureFreeze week, the trunk (bzr.dev) is open in a limited
1507
way: only low risk changes, critical and high priority fixes are accepted
1508
during this time. At the end of FeatureFreeze, a branch is created for the
1509
first Release Candidate and the trunk is reopened for general development
1510
on the *next* release. A week or so later, the final release is packaged
1511
assuming no serious problems were encountered with the one or more Release
1515
There is a one week overlap between the start of one release and
1516
the end of the previous one.
1519
1621
Communicating and Coordinating
1520
1622
------------------------------
added
removed
doc/developers/HACKING.txt
