136
If you change the behaviour of a command, please update its docstring
137
in bzrlib/commands.py. This is displayed by the 'bzr help' command.
136
When you change bzrlib, please update the relevant documentation for the
137
change you made: Changes to commands should update their help, and
138
possibly end user tutorials; changes to the core library should be
139
reflected in API documentation.
144
The docstring of a command is used by ``bzr help`` to generate help output
145
for the command. The list 'takes_options' attribute on a command is used by
146
``bzr help`` to document the options for the command - the command
147
docstring does not need to document them. Finally, the '_see_also'
148
attribute on a command can be used to reference other related help topics.
292
306
At this point, all of these exist as a ``ImportReplacer`` object, ready to
293
307
be imported once a member is accessed. Also, when importing a module into
294
308
the local namespace, which is likely to clash with variable names, it is
295
recommended to prefix it as ``_mod_<module>``. This makes it clean that
309
recommended to prefix it as ``_mod_<module>``. This makes it clearer that
296
310
the variable is a module, and these object should be hidden anyway, since
297
311
they shouldn't be imported into other namespaces.
373
387
tests subdirectory under the package being tested.
375
389
For example, tests for merge3 in bzrlib belong in bzrlib/tests/test_merge3.py.
376
See bzrlib/selftest/test_sampler.py for a template test script.
390
See bzrlib/tests/test_sampler.py for a template test script.
378
392
Tests can be written for the UI or for individual areas of the library.
379
393
Choose whichever is appropriate: if adding a new command, or a new command
429
443
./bzr selftest -v blackbox
431
To skip a particular test (or set of tests), you need to use a negative
434
./bzr selftest '^(?!.*blackbox)'
445
To skip a particular test (or set of tests), use the --exclude option
446
(shorthand -x) like so::
448
./bzr selftest -v -x blackbox
450
To list tests without running them, use the --list-only option like so::
452
./bzr selftest --list-only
454
This option can be combined with other selftest options (like -x) and
455
filter patterns to understand their effect.
437
458
Errors and exceptions
499
Bazaar has a few facilities to help debug problems by going into pdb_, the
502
.. _pdb: http://docs.python.org/lib/debugger-commands.html
504
If the ``BZR_PDB`` environment variable is set
505
then bzr will go into pdb post-mortem mode when an unhandled exception
508
If you send a SIGQUIT signal to bzr, which can be done by pressing C-\ on Unix,
509
bzr will go into the debugger immediately. You can continue execution by
510
typing ``c``. This can be disabled if necessary by setting the
511
environment variable ``BZR_SIGQUIT_PDB=0``.
586
626
valid characters are generated where possible.
632
The ``bzrlib.osutils`` module has many useful helper functions, including
633
some more portable variants of functions in the standard library.
635
In particular, don't use ``shutil.rmtree`` unless it's acceptable for it
636
to fail on Windows if some files are readonly or still open elsewhere.
637
Use ``bzrlib.osutils.rmtree`` instead.
589
640
Merge/review process
590
641
====================
592
643
If you'd like to propose a change, please post to the
593
bazaar-ng@lists.canonical.com list with a patch, bzr changeset, or link to a
644
bazaar@lists.canonical.com list with a patch, bzr changeset, or link to a
594
645
branch. Please put '[patch]' in the subject so we can pick them out, and
595
646
include some text explaining the change. Remember to put an update to the NEWS
596
647
file in your diff, if it makes any changes visible to users or plugin
629
680
so, please reply and say so.)
686
We write some extensions in C using pyrex. We design these to work in
689
* User with no C compiler
690
* User with C compiler
693
The recommended way to install bzr is to have a C compiler so that the
694
extensions can be built, but if no C compiler is present, the pure python
695
versions we supply will work, though more slowly.
697
For developers we recommend that pyrex be installed, so that the C
698
extensions can be changed if needed.
700
For the C extensions, the extension module should always match the
701
original python one in all respects (modulo speed). This should be
702
maintained over time.
704
To create an extension, add rules to setup.py for building it with pyrex,
705
and with distutils. Now start with an empty .pyx file. At the top add
706
"include 'yourmodule.py'". This will import the contents of foo.py into this
707
file at build time - remember that only one module will be loaded at
708
runtime. Now you can subclass classes, or replace functions, and only your
709
changes need to be present in the .pyx file.
711
Note that pyrex does not support all 2.4 programming idioms, so some
712
syntax changes may be required. I.e.
714
- 'from foo import (bar, gam)' needs to change to not use the brackets.
715
- 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar'
717
If the changes are too dramatic, consider
718
maintaining the python code twice - once in the .pyx, and once in the .py,
719
and no longer including the .py file.
632
721
Making installers for OS Windows
633
722
================================
634
723
To build a win32 installer, see the instructions on the wiki page:
added
removed
HACKING
