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
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
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
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
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?`_.)
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
123
the Bazaar trunk. Go to
124
124
<https://launchpad.net/~<your_lp_username>/bzr/meaningful_name_here> and choose
125
125
"Propose for merging into another branch". Select "lp:bzr" to hand
126
your changes off to the Breezy developers for review and merging.
126
your changes off to the Bazaar developers for review and merging.
128
128
Alternatively, after pushing you can use the ``lp-propose`` command to
129
129
create the merge proposal.
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
224
224
* create a local copy of the main development branch (bzr.dev) by using
227
brz branch lp:brz bzr.dev
227
bzr branch lp:bzr bzr.dev
229
229
* keep your copy of bzr.dev pristine (by not developing in it) and keep
230
it up to date (by using brz pull)
230
it up to date (by using bzr pull)
232
232
* create a new branch off your local bzr.dev copy for each issue
233
233
(bug or feature) you are working on.
247
247
Some of the key files in this directory are:
250
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
251
251
short and just does some checks then jumps into bzrlib.
254
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
Installs Breezy system-wide or to your home directory. To perform
259
development work on Breezy it is not required to run this file - you
260
can simply run the Breezy command from the top level directory of your
258
Installs Bazaar system-wide or to your home directory. To perform
259
development work on Bazaar it is not required to run this file - you
260
can simply run the bzr command from the top level directory of your
261
261
development copy. Note: That if you run setup.py this will create a
262
262
'build' directory in your development branch. There's nothing wrong
263
263
with this but don't be confused by it. The build process puts a copy
269
269
Possibly the most exciting folder of all, bzrlib holds the main code
270
270
base. This is where you will go to edit python files and contribute to
274
Holds documentation on a whole range of things on Breezy from the
275
origination of ideas within the project to information on Breezy
274
Holds documentation on a whole range of things on Bazaar from the
275
origination of ideas within the project to information on Bazaar
276
276
features and use cases. Within this directory there is a subdirectory
277
277
for each translation into a human language. All the documentation
278
278
is in the ReStructuredText markup language.
281
Documentation specifically targeted at Breezy and plugin developers.
281
Documentation specifically targeted at Bazaar and plugin developers.
282
282
(Including this document.)
284
284
doc/en/release-notes/
286
Detailed changes in each Breezy release (there is one file by series:
286
Detailed changes in each Bazaar release (there is one file by series:
287
287
bzr-2.3.txt, bzr-2.4.txt, etc) that can affect users or plugin
290
290
doc/en/whats-new/
292
High-level summaries of changes in each Breezy release (there is one
292
High-level summaries of changes in each Bazaar release (there is one
293
293
file by series: whats-new-in-2.3.txt, whats-new-in-2.4.txt, etc).
296
296
Automatically-generated API reference information is available at
297
297
<http://people.canonical.com/~mwh/bzrlibapi/>.
299
See also the `Breezy Architectural Overview
299
See also the `Bazaar Architectural Overview
300
300
<http://doc.bazaar.canonical.com/developers/overview.html>`_.
307
307
===================
309
309
We don't change APIs in stable branches: any supported symbol in a stable
310
release of Breezy must not be altered in any way that would result in
310
release of bzr must not be altered in any way that would result in
311
311
breaking existing code that uses it. That means that method names,
312
312
parameter ordering, parameter names, variable and attribute names etc must
313
313
not be changed without leaving a 'deprecated forwarder' behind. This even
368
368
General Guidelines
369
369
==================
374
The copyright policy for bzr was recently made clear in this email (edited
375
for grammatical correctness)::
377
The attached patch cleans up the copyright and license statements in
378
the bzr source. It also adds tests to help us remember to add them
379
with the correct text.
381
We had the problem that lots of our files were "Copyright Canonical
382
Development Ltd" which is not a real company, and some other variations
383
on this theme. Also, some files were missing the GPL statements.
385
I want to be clear about the intent of this patch, since copyright can
386
be a little controversial.
388
1) The big motivation for this is not to shut out the community, but
389
just to clean up all of the invalid copyright statements.
391
2) It has been the general policy for bzr that we want a single
392
copyright holder for all of the core code. This is following the model
393
set by the FSF, which makes it easier to update the code to a new
394
license in case problems are encountered. (For example, if we want to
395
upgrade the project universally to GPL v3 it is much simpler if there is
396
a single copyright holder). It also makes it clearer if copyright is
397
ever debated, there is a single holder, which makes it easier to defend
398
in court, etc. (I think the FSF position is that if you assign them
399
copyright, they can defend it in court rather than you needing to, and
400
I'm sure Canonical would do the same).
401
As such, Canonical has requested copyright assignments from all of the
404
3) If someone wants to add code and not attribute it to Canonical, there
405
is a specific list of files that are excluded from this check. And the
406
test failure indicates where that is, and how to update it.
408
4) If anyone feels that I changed a copyright statement incorrectly, just
409
let me know, and I'll be happy to correct it. Whenever you have large
410
mechanical changes like this, it is possible to make some mistakes.
412
Just to reiterate, this is a community project, and it is meant to stay
413
that way. Core bzr code is copyright Canonical for legal reasons, and
414
the tests are just there to help us maintain that.
371
417
Miscellaneous Topics
372
418
####################
377
Breezy has a few facilities to help debug problems by going into pdb_, the
423
Bazaar has a few facilities to help debug problems by going into pdb_, the
380
426
.. _pdb: http://docs.python.org/lib/debugger-commands.html
382
428
If the ``BZR_PDB`` environment variable is set
383
then brz will go into pdb post-mortem mode when an unhandled exception
429
then bzr will go into pdb post-mortem mode when an unhandled exception
386
If you send a SIGQUIT or SIGBREAK signal to brz then it will drop into the
432
If you send a SIGQUIT or SIGBREAK signal to bzr then it will drop into the
387
433
debugger immediately. SIGQUIT can be generated by pressing Ctrl-\\ on
388
434
Unix. SIGBREAK is generated with Ctrl-Pause on Windows (some laptops have
389
435
this as Fn-Pause). You can continue execution by typing ``c``. This can
409
455
Debug flags may have effects other than just emitting trace messages.
411
Run ``brz help global-options`` to see them all.
457
Run ``bzr help global-options`` to see them all.
413
459
These flags may also be set as a comma-separated list in the
414
``debug_flags`` option in e.g. ``~/.config/breezy/breezy.conf``. (Note
415
that it must be in this global file, not in the branch or location
416
configuration, because it's currently only loaded at startup time.) For
417
instance you may want to always record hpss traces and to see full error
460
``debug_flags`` option in e.g. ``~/.bazaar/bazaar.conf``. (Note that it
461
must be in this global file, not in the branch or location configuration,
462
because it's currently only loaded at startup time.) For instance you may
463
want to always record hpss traces and to see full error tracebacks::
420
465
debug_flags = hpss, error
452
497
marker (typically '?'), and no exception will be raised. This is for
453
498
any command which generates text for the user to review, rather than
454
499
for automated processing.
455
For example: ``brz log`` should not fail if one of the entries has text
500
For example: ``bzr log`` should not fail if one of the entries has text
456
501
that cannot be displayed.
459
504
Attempting to print an unprintable character will cause a UnicodeError.
460
505
This is for commands that are intended more as scripting support, rather
461
506
than plain user review.
462
For example: ``brz ls`` is designed to be used with shell scripting. One
463
use would be ``brz ls --null --unknowns | xargs -0 rm``. If ``bzr``
507
For example: ``bzr ls`` is designed to be used with shell scripting. One
508
use would be ``bzr ls --null --unknowns | xargs -0 rm``. If ``bzr``
464
509
printed a filename with a '?', the wrong file could be deleted. (At the
465
510
very least, the correct file would not be deleted). An error is used to
466
511
indicate that the requested action could not be performed.
487
532
C Extension Modules
488
533
===================
490
We write some extensions in C using Cython. We design these to work in
535
We write some extensions in C using pyrex. We design these to work in
493
538
* User with no C compiler
494
539
* User with C compiler
497
The recommended way to install Breezy is to have a C compiler so that the
542
The recommended way to install bzr is to have a C compiler so that the
498
543
extensions can be built, but if no C compiler is present, the pure python
499
544
versions we supply will work, though more slowly.
501
For developers we recommend that Cython be installed, so that the C
546
For developers we recommend that pyrex be installed, so that the C
502
547
extensions can be changed if needed.
504
549
For the C extensions, the extension module should always match the
505
550
original python one in all respects (modulo speed). This should be
506
551
maintained over time.
508
To create an extension, add rules to setup.py for building it with Cython ,
553
To create an extension, add rules to setup.py for building it with pyrex,
509
554
and with distutils. Now start with an empty .pyx file. At the top add
510
555
"include 'yourmodule.py'". This will import the contents of foo.py into this
511
556
file at build time - remember that only one module will be loaded at
512
557
runtime. Now you can subclass classes, or replace functions, and only your
513
558
changes need to be present in the .pyx file.
560
Note that pyrex does not support all 2.4 programming idioms, so some
561
syntax changes may be required. I.e.
563
- 'from foo import (bar, gam)' needs to change to not use the brackets.
564
- 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar'
566
If the changes are too dramatic, consider
567
maintaining the python code twice - once in the .pyx, and once in the .py,
568
and no longer including the .py file.
515
571
Making Installers for OS Windows
516
572
================================
517
573
To build a win32 installer, see the instructions on the wiki page:
526
582
What is a Core Developer?
527
583
-------------------------
529
While everyone in the Breezy community is welcome and encouraged to
585
While everyone in the Bazaar community is welcome and encouraged to
530
586
propose and submit changes, a smaller team is reponsible for pulling those
531
587
changes together into a cohesive whole. In addition to the general developer
532
588
stuff covered above, "core" developers have responsibility for:
534
590
* reviewing changes
535
591
* planning releases
536
* managing releases (see `Releasing Breezy <http://doc.bazaar.canonical.com/developers/releasing.html>`_)
592
* managing releases (see `Releasing Bazaar <http://doc.bazaar.canonical.com/developers/releasing.html>`_)
539
595
Removing barriers to community participation is a key reason for adopting
added
removed
doc/developers/HACKING.txt
