1
1
======================
3
3
======================
5
This document describes the Breezy internals and the development process.
6
It's meant for people interested in developing Breezy, and some parts will
7
also be useful to people developing Breezy plugins.
5
This document describes the Bazaar internals and the development process.
6
It's meant for people interested in developing Bazaar, and some parts will
7
also be useful to people developing Bazaar plugins.
9
9
If you have any questions or something seems to be incorrect, unclear or
10
10
missing, please talk to us in ``irc://irc.freenode.net/#bzr``, or write to
11
the Breezy mailing list. To propose a correction or addition to this
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
14
The latest developer documentation can be found online at
15
https://www.breezy-vcs.org/developers/.
15
http://doc.bazaar.canonical.com/developers/.
20
Exploring the Breezy Platform
20
Exploring the Bazaar Platform
21
21
=============================
23
23
Before making changes, it's a good idea to explore the work already
26
26
perhaps someone else has already fixed it?
28
28
To answer these questions and more, take a moment to explore the
29
overall Breezy Platform. Here are some links to browse:
29
overall Bazaar Platform. Here are some links to browse:
31
31
* The Plugins page on the Wiki - http://wiki.bazaar.canonical.com/BzrPlugins
33
* The Breezy product family on Launchpad - https://launchpad.net/breezy
33
* The Bazaar product family on Launchpad - https://launchpad.net/bazaar
35
* Bug Tracker for the core product - https://bugs.launchpad.net/brz/
35
* Bug Tracker for the core product - https://bugs.launchpad.net/bzr/
37
37
If nothing else, perhaps you'll find inspiration in how other developers
38
38
have solved their challenges.
41
41
=======================
43
43
Ad-hoc performance work can also be done. One useful tool is the 'evil' debug
44
flag. For instance running ``brz -Devil commit -m "test"`` will log a backtrace
45
to the Breezy log file for every method call which triggers a slow or non-scalable
46
part of the breezy library. So checking that a given command with ``-Devil`` has
44
flag. For instance running ``bzr -Devil commit -m "test"`` will log a backtrace
45
to the bzr log file for every method call which triggers a slow or non-scalable
46
part of the bzr library. So checking that a given command with ``-Devil`` has
47
47
no backtraces logged to the log file is a good way to find problem function
48
48
calls that might be nested deep in the code base.
50
50
Planning and Discussing Changes
51
51
===============================
53
There is a very active community around Breezy. Mostly we meet on IRC
54
(#bzr on irc.freenode.net) and on the mailing list. To join the Breezy
55
community, see https://www.breezy-vcs.org/pages/support.html.
53
There is a very active community around Bazaar. Mostly we meet on IRC
54
(#bzr on irc.freenode.net) and on the mailing list. To join the Bazaar
55
community, see http://wiki.bazaar.canonical.com/BzrSupport.
57
57
If you are planning to make a change, it's a very good idea to mention it
58
58
on the IRC channel and/or on the mailing list. There are many advantages
70
70
friendly, helpful and always keen to welcome newcomers.
73
Breezy Development in a Nutshell
73
Bazaar Development in a Nutshell
74
74
================================
76
76
.. was from http://wiki.bazaar.canonical.com/BzrGivingBack
78
One of the fun things about working on a version control system like Breezy is
78
One of the fun things about working on a version control system like Bazaar is
79
79
that the users have a high level of proficiency in contributing back into
80
80
the tool. Consider the following very brief introduction to contributing back
81
to Breezy. More detailed instructions are in the following sections.
81
to Bazaar. More detailed instructions are in the following sections.
87
87
copy of bzr.dev?`_.)
90
$ brz init-shared-repo ~/bzr
92
$ brz branch lp:brz bzr.dev
92
$ bzr branch lp:bzr bzr.dev
94
94
Now make your own branch::
96
$ brz branch bzr.dev 123456-my-bugfix
96
$ bzr branch bzr.dev 123456-my-bugfix
98
98
This will give you a branch called "123456-my-bugfix" that you can work on
99
99
and commit in. Here, you can study the code, make a fix or a new feature.
100
100
Feel free to commit early and often (after all, it's your branch!).
102
102
Documentation improvements are an easy place to get started giving back to the
103
Breezy project. The documentation is in the `doc/` subdirectory of the Breezy
103
Bazaar project. The documentation is in the `doc/` subdirectory of the Bazaar
106
106
When you are done, make sure that you commit your last set of changes as well!
110
110
Making a Merge Proposal
111
111
-----------------------
113
The Breezy developers use Launchpad to further enable a truly distributed
114
style of development. Anyone can propose a branch for merging into the Breezy
113
The Bazaar developers use Launchpad to further enable a truly distributed
114
style of development. Anyone can propose a branch for merging into the Bazaar
115
115
trunk. To start this process, you need to push your branch to Launchpad. To
116
116
do this, you will need a Launchpad account and user name, e.g.
117
117
`your_lp_username`. You can push your branch to Launchpad directly from
120
$ brz push lp:~<your_lp_username>/bzr/meaningful_name_here
120
$ bzr push lp:~your_lp_username/bzr/meaningful_name_here
122
122
After you have pushed your branch, you will need to propose it for merging to
123
the Breezy trunk. Go to
124
<https://launchpad.net/~<your_lp_username>/bzr/meaningful_name_here> and choose
125
"Propose for merging into another branch". Select "lp:bzr" to hand
126
your changes off to the Breezy developers for review and merging.
123
the Bazaar trunk. Go to
124
<https://launchpad.net/your_lp_username/bzr/meaningful_name_here> and choose
125
"Propose for merging into another branch". Select "~bzr/bzr/trunk" to hand
126
your changes off to the Bazaar developers for review and merging.
128
Alternatively, after pushing you can use the ``propose`` command to
128
Alternatively, after pushing you can use the ``lp-propose`` command to
129
129
create the merge proposal.
131
131
Using a meaningful name for your branch will help you and the reviewer(s)
165
165
Making a local mirror of bzr.dev is not strictly necessary, but it means
167
- You can use that copy of bzr.dev as your main brz executable, and keep it
168
up-to-date using ``brz pull``.
167
- You can use that copy of bzr.dev as your main bzr executable, and keep it
168
up-to-date using ``bzr pull``.
169
169
- Certain operations are faster, and can be done when offline. For example:
172
- ``brz diff -r ancestor:...``
172
- ``bzr diff -r ancestor:...``
175
175
- When it's time to create your next branch, it's more convenient. When you
176
176
have further contributions to make, you should do them in their own branch::
179
$ brz branch bzr.dev additional_fixes
179
$ bzr branch bzr.dev additional_fixes
180
180
$ cd additional_fixes # hack, hack, hack
202
202
* Launchpad - https://launchpad.net/
204
* Breezy - https://www.breezy-vcs.org/
204
* Bazaar - http://bazaar.canonical.com/
206
206
* Patch Queue Manager - https://launchpad.net/pqm/
208
For further information, see <https://www.breezy-vcs.org/developers/>.
211
Preparing a Sandbox for Making Changes to Breezy
208
For further information, see <http://wiki.bazaar.canonical.com/BzrDevelopment>.
213
Preparing a Sandbox for Making Changes to Bazaar
212
214
================================================
214
Breezy supports many ways of organising your work. See
216
Bazaar supports many ways of organising your work. See
215
217
http://wiki.bazaar.canonical.com/SharedRepositoryLayouts for a summary of the
216
218
popular alternatives.
245
247
Some of the key files in this directory are:
248
The command you run to start Breezy itself. This script is pretty
250
The command you run to start Bazaar itself. This script is pretty
249
251
short and just does some checks then jumps into bzrlib.
252
This file covers a brief introduction to Breezy and lists some of its
254
This file covers a brief introduction to Bazaar and lists some of its
258
Summary of changes in each Bazaar release that can affect users or
256
Installs Breezy system-wide or to your home directory. To perform
257
development work on Breezy it is not required to run this file - you
258
can simply run the Breezy command from the top level directory of your
262
Installs Bazaar system-wide or to your home directory. To perform
263
development work on Bazaar it is not required to run this file - you
264
can simply run the bzr command from the top level directory of your
259
265
development copy. Note: That if you run setup.py this will create a
260
266
'build' directory in your development branch. There's nothing wrong
261
267
with this but don't be confused by it. The build process puts a copy
267
273
Possibly the most exciting folder of all, bzrlib holds the main code
268
274
base. This is where you will go to edit python files and contribute to
272
Holds documentation on a whole range of things on Breezy from the
273
origination of ideas within the project to information on Breezy
278
Holds documentation on a whole range of things on Bazaar from the
279
origination of ideas within the project to information on Bazaar
274
280
features and use cases. Within this directory there is a subdirectory
275
281
for each translation into a human language. All the documentation
276
282
is in the ReStructuredText markup language.
279
Documentation specifically targeted at Breezy and plugin developers.
285
Documentation specifically targeted at Bazaar and plugin developers.
280
286
(Including this document.)
282
doc/en/release-notes/
284
Detailed changes in each Breezy release (there is one file by series:
285
bzr-2.3.txt, bzr-2.4.txt, etc) that can affect users or plugin
290
High-level summaries of changes in each Breezy release (there is one
291
file by series: whats-new-in-2.3.txt, whats-new-in-2.4.txt, etc).
294
290
Automatically-generated API reference information is available at
295
<https://www.breezy-vcs.org/developers/api/>.
291
<http://starship.python.net/crew/mwh/bzrlibapi/>.
297
See also the `Breezy Architectural Overview
298
<https://www.breezy-vcs.org/developers/overview.html>`_.
293
See also the `Bazaar Architectural Overview
294
<http://doc.bazaar.canonical.com/developers/overview.html>`_.
366
362
General Guidelines
367
363
==================
368
The copyright policy for bzr was recently made clear in this email (edited
369
for grammatical correctness)::
371
The attached patch cleans up the copyright and license statements in
372
the bzr source. It also adds tests to help us remember to add them
373
with the correct text.
375
We had the problem that lots of our files were "Copyright Canonical
376
Development Ltd" which is not a real company, and some other variations
377
on this theme. Also, some files were missing the GPL statements.
379
I want to be clear about the intent of this patch, since copyright can
380
be a little controversial.
382
1) The big motivation for this is not to shut out the community, but
383
just to clean up all of the invalid copyright statements.
385
2) It has been the general policy for bzr that we want a single
386
copyright holder for all of the core code. This is following the model
387
set by the FSF, which makes it easier to update the code to a new
388
license in case problems are encountered. (For example, if we want to
389
upgrade the project universally to GPL v3 it is much simpler if there is
390
a single copyright holder). It also makes it clearer if copyright is
391
ever debated, there is a single holder, which makes it easier to defend
392
in court, etc. (I think the FSF position is that if you assign them
393
copyright, they can defend it in court rather than you needing to, and
394
I'm sure Canonical would do the same).
395
As such, Canonical has requested copyright assignments from all of the
398
3) If someone wants to add code and not attribute it to Canonical, there
399
is a specific list of files that are excluded from this check. And the
400
test failure indicates where that is, and how to update it.
402
4) If anyone feels that I changed a copyright statement incorrectly, just
403
let me know, and I'll be happy to correct it. Whenever you have large
404
mechanical changes like this, it is possible to make some mistakes.
406
Just to reiterate, this is a community project, and it is meant to stay
407
that way. Core bzr code is copyright Canonical for legal reasons, and
408
the tests are just there to help us maintain that.
369
411
Miscellaneous Topics
370
412
####################
375
Breezy has a few facilities to help debug problems by going into pdb_, the
417
Bazaar has a few facilities to help debug problems by going into pdb_, the
378
420
.. _pdb: http://docs.python.org/lib/debugger-commands.html
380
422
If the ``BZR_PDB`` environment variable is set
381
then brz will go into pdb post-mortem mode when an unhandled exception
423
then bzr will go into pdb post-mortem mode when an unhandled exception
384
If you send a SIGQUIT or SIGBREAK signal to brz then it will drop into the
426
If you send a SIGQUIT or SIGBREAK signal to bzr then it will drop into the
385
427
debugger immediately. SIGQUIT can be generated by pressing Ctrl-\\ on
386
428
Unix. SIGBREAK is generated with Ctrl-Pause on Windows (some laptops have
387
429
this as Fn-Pause). You can continue execution by typing ``c``. This can
388
430
be disabled if necessary by setting the environment variable
389
431
``BZR_SIGQUIT_PDB=0``.
391
All tests inheriting from bzrlib.tests.TestCase can use ``self.debug()``
392
instead of the longer ``import pdb; pdb.set_trace()``. The former also works
393
when ``stdin/stdout`` are redirected (by using the original ``stdin/stdout``
394
file handles at the start of the ``bzr`` script) while the later doesn't.
395
``bzrlib.debug.set_trace()`` also uses the original ``stdin/stdout`` file
401
Breezy accepts some global options starting with ``-D`` such as
437
Bazaar accepts some global options starting with ``-D`` such as
402
438
``-Dhpss``. These set a value in `bzrlib.debug.debug_flags`, and
403
439
typically cause more information to be written to the trace file. Most
404
440
`mutter` calls should be guarded by a check of those flags so that we
407
443
Debug flags may have effects other than just emitting trace messages.
409
Run ``brz help global-options`` to see them all.
445
Run ``bzr help global-options`` to see them all.
411
447
These flags may also be set as a comma-separated list in the
412
``debug_flags`` option in e.g. ``~/.config/breezy/breezy.conf``. (Note
413
that it must be in this global file, not in the branch or location
414
configuration, because it's currently only loaded at startup time.) For
415
instance you may want to always record hpss traces and to see full error
448
``debug_flags`` option in e.g. ``~/.bazaar/bazaar.conf``. (Note that it
449
must be in this global file, not in the branch or location configuration,
450
because it's currently only loaded at startup time.) For instance you may
451
want to always record hpss traces and to see full error tracebacks::
418
453
debug_flags = hpss, error
450
485
marker (typically '?'), and no exception will be raised. This is for
451
486
any command which generates text for the user to review, rather than
452
487
for automated processing.
453
For example: ``brz log`` should not fail if one of the entries has text
488
For example: ``bzr log`` should not fail if one of the entries has text
454
489
that cannot be displayed.
457
492
Attempting to print an unprintable character will cause a UnicodeError.
458
493
This is for commands that are intended more as scripting support, rather
459
494
than plain user review.
460
For example: ``brz ls`` is designed to be used with shell scripting. One
461
use would be ``brz ls --null --unknowns | xargs -0 rm``. If ``bzr``
495
For example: ``bzr ls`` is designed to be used with shell scripting. One
496
use would be ``bzr ls --null --unknowns | xargs -0 rm``. If ``bzr``
462
497
printed a filename with a '?', the wrong file could be deleted. (At the
463
498
very least, the correct file would not be deleted). An error is used to
464
499
indicate that the requested action could not be performed.
485
520
C Extension Modules
486
521
===================
488
We write some extensions in C using Cython. We design these to work in
523
We write some extensions in C using pyrex. We design these to work in
491
526
* User with no C compiler
492
527
* User with C compiler
495
The recommended way to install Breezy is to have a C compiler so that the
530
The recommended way to install bzr is to have a C compiler so that the
496
531
extensions can be built, but if no C compiler is present, the pure python
497
532
versions we supply will work, though more slowly.
499
For developers we recommend that Cython be installed, so that the C
534
For developers we recommend that pyrex be installed, so that the C
500
535
extensions can be changed if needed.
502
537
For the C extensions, the extension module should always match the
503
538
original python one in all respects (modulo speed). This should be
504
539
maintained over time.
506
To create an extension, add rules to setup.py for building it with Cython ,
541
To create an extension, add rules to setup.py for building it with pyrex,
507
542
and with distutils. Now start with an empty .pyx file. At the top add
508
543
"include 'yourmodule.py'". This will import the contents of foo.py into this
509
544
file at build time - remember that only one module will be loaded at
510
545
runtime. Now you can subclass classes, or replace functions, and only your
511
546
changes need to be present in the .pyx file.
548
Note that pyrex does not support all 2.4 programming idioms, so some
549
syntax changes may be required. I.e.
551
- 'from foo import (bar, gam)' needs to change to not use the brackets.
552
- 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar'
554
If the changes are too dramatic, consider
555
maintaining the python code twice - once in the .pyx, and once in the .py,
556
and no longer including the .py file.
513
559
Making Installers for OS Windows
514
560
================================
515
561
To build a win32 installer, see the instructions on the wiki page:
524
570
What is a Core Developer?
525
571
-------------------------
527
While everyone in the Breezy community is welcome and encouraged to
573
While everyone in the Bazaar community is welcome and encouraged to
528
574
propose and submit changes, a smaller team is reponsible for pulling those
529
575
changes together into a cohesive whole. In addition to the general developer
530
576
stuff covered above, "core" developers have responsibility for:
532
578
* reviewing changes
579
* reviewing blueprints
533
580
* planning releases
534
* managing releases (see `Releasing Breezy <https://www.breezy-vcs.org/developers/releasing.html>`_)
581
* managing releases (see `Releasing Bazaar <http://doc.bazaar.canonical.com/developers/releasing.html>`_)
537
584
Removing barriers to community participation is a key reason for adopting