/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/developers/HACKING.txt

  • Committer: John Arbash Meinel
  • Date: 2011-04-22 14:12:22 UTC
  • mfrom: (5809 +trunk)
  • mto: This revision was merged to the branch mainline in revision 5836.
  • Revision ID: john@arbash-meinel.com-20110422141222-nx2j0hbkihcb8j16
Merge newer bzr.dev and resolve conflicts.
Try to write some documentation about how the _dirblock_state works.
Fix up the tests so that they pass again.

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
1
======================
2
 
Breezy Developer Guide
 
2
Bazaar Developer Guide
3
3
======================
4
4
 
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.
8
8
 
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.
13
13
 
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/.
16
16
 
17
17
Getting Started
18
18
###############
19
19
 
20
 
Exploring the Breezy Platform
 
20
Exploring the Bazaar Platform
21
21
=============================
22
22
 
23
23
Before making changes, it's a good idea to explore the work already
26
26
perhaps someone else has already fixed it?
27
27
 
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:
30
30
 
31
31
* The Plugins page on the Wiki - http://wiki.bazaar.canonical.com/BzrPlugins
32
32
 
33
 
* The Breezy product family on Launchpad - https://launchpad.net/breezy
 
33
* The Bazaar product family on Launchpad - https://launchpad.net/bazaar
34
34
 
35
 
* Bug Tracker for the core product - https://bugs.launchpad.net/brz/
 
35
* Bug Tracker for the core product - https://bugs.launchpad.net/bzr/
36
36
 
37
37
If nothing else, perhaps you'll find inspiration in how other developers
38
38
have solved their challenges.
41
41
=======================
42
42
 
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.
49
49
 
50
50
Planning and Discussing Changes
51
51
===============================
52
52
 
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.
56
56
 
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.
71
71
 
72
72
 
73
 
Breezy Development in a Nutshell
 
73
Bazaar Development in a Nutshell
74
74
================================
75
75
 
76
76
.. was from http://wiki.bazaar.canonical.com/BzrGivingBack
77
77
 
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.
82
82
 
83
83
Making the change
84
84
-----------------
87
87
copy of bzr.dev?`_.)
88
88
::
89
89
 
90
 
 $ brz init-shared-repo ~/bzr
 
90
 $ bzr init-repo ~/bzr
91
91
 $ cd ~/bzr
92
 
 $ brz branch lp:brz bzr.dev
 
92
 $ bzr branch lp:bzr bzr.dev
93
93
 
94
94
Now make your own branch::
95
95
 
96
 
 $ brz branch bzr.dev 123456-my-bugfix
 
96
 $ bzr branch bzr.dev 123456-my-bugfix
97
97
 
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!).
101
101
 
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
104
104
source tree.
105
105
 
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
-----------------------
112
112
 
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
118
 
Breezy::
 
118
Bazaar::
119
119
 
120
 
  $ brz push lp:~<your_lp_username>/bzr/meaningful_name_here
 
120
  $ bzr push lp:~your_lp_username/bzr/meaningful_name_here
121
121
 
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.
127
127
 
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.
130
130
 
131
131
Using a meaningful name for your branch will help you and the reviewer(s)
164
164
 
165
165
Making a local mirror of bzr.dev is not strictly necessary, but it means
166
166
 
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:
170
170
 
171
 
  - ``brz bundle``
172
 
  - ``brz diff -r ancestor:...``
173
 
  - ``brz merge``
 
171
  - ``bzr bundle``
 
172
  - ``bzr diff -r ancestor:...``
 
173
  - ``bzr merge``
174
174
 
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::
177
177
 
178
178
    $ cd ~/bzr
179
 
    $ brz branch bzr.dev additional_fixes
 
179
    $ bzr branch bzr.dev additional_fixes
180
180
    $ cd additional_fixes # hack, hack, hack
181
181
 
182
182
 
201
201
 
202
202
* Launchpad - https://launchpad.net/
203
203
 
204
 
* Breezy - https://www.breezy-vcs.org/
 
204
* Bazaar - http://bazaar.canonical.com/
205
205
 
206
206
* Patch Queue Manager - https://launchpad.net/pqm/
207
207
 
208
 
For further information, see <https://www.breezy-vcs.org/developers/>.
209
 
 
210
 
 
211
 
Preparing a Sandbox for Making Changes to Breezy
 
208
For further information, see <http://wiki.bazaar.canonical.com/BzrDevelopment>.
 
209
 
 
210
 
 
211
 
 
212
 
 
213
Preparing a Sandbox for Making Changes to Bazaar
212
214
================================================
213
215
 
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.
217
219
 
222
224
* create a local copy of the main development branch (bzr.dev) by using
223
225
  this command::
224
226
 
225
 
    brz branch lp:brz bzr.dev
 
227
    bzr branch lp:bzr bzr.dev
226
228
 
227
229
* keep your copy of bzr.dev pristine (by not developing in it) and keep
228
 
  it up to date (by using brz pull)
 
230
  it up to date (by using bzr pull)
229
231
 
230
232
* create a new branch off your local bzr.dev copy for each issue
231
233
  (bug or feature) you are working on.
245
247
Some of the key files in this directory are:
246
248
 
247
249
bzr
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.
250
252
 
251
 
README.rst
252
 
    This file covers a brief introduction to Breezy and lists some of its
 
253
README
 
254
    This file covers a brief introduction to Bazaar and lists some of its
253
255
    key features.
254
256
 
 
257
NEWS
 
258
    Summary of changes in each Bazaar release that can affect users or
 
259
    plugin developers.
 
260
 
255
261
setup.py
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
266
272
bzrlib
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
269
 
    Breezy.
 
275
    Bazaar.
270
276
 
271
277
doc
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.
277
283
 
278
284
doc/developers
279
 
    Documentation specifically targeted at Breezy and plugin developers.
 
285
    Documentation specifically targeted at Bazaar and plugin developers.
280
286
    (Including this document.)
281
287
 
282
 
doc/en/release-notes/
283
 
 
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
286
 
    developers.
287
 
 
288
 
doc/en/whats-new/
289
 
 
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).
292
288
 
293
289
 
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/>.
296
292
 
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>`_.
299
295
 
300
296
 
301
297
Core Topics
305
301
===================
306
302
 
307
303
We don't change APIs in stable branches: any supported symbol in a stable
308
 
release of Breezy must not be altered in any way that would result in
 
304
release of bzr must not be altered in any way that would result in
309
305
breaking existing code that uses it. That means that method names,
310
306
parameter ordering, parameter names, variable and attribute names etc must
311
307
not be changed without leaving a 'deprecated forwarder' behind. This even
366
362
General Guidelines
367
363
==================
368
364
 
 
365
Copyright
 
366
---------
 
367
 
 
368
The copyright policy for bzr was recently made clear in this email (edited
 
369
for grammatical correctness)::
 
370
 
 
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.
 
374
 
 
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.
 
378
 
 
379
    I want to be clear about the intent of this patch, since copyright can
 
380
    be a little controversial.
 
381
 
 
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.
 
384
 
 
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
 
396
    major contributers.
 
397
 
 
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.
 
401
 
 
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.
 
405
 
 
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.
 
409
 
 
410
 
369
411
Miscellaneous Topics
370
412
####################
371
413
 
372
414
Debugging
373
415
=========
374
416
 
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
376
418
Python debugger.
377
419
 
378
420
.. _pdb: http://docs.python.org/lib/debugger-commands.html
379
421
 
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
382
424
occurs.
383
425
 
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``.
390
432
 
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
396
 
handles.
397
433
 
398
434
Debug Flags
399
435
===========
400
436
 
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
406
442
 
407
443
Debug flags may have effects other than just emitting trace messages.
408
444
 
409
 
Run ``brz help global-options`` to see them all.
 
445
Run ``bzr help global-options`` to see them all.
410
446
 
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
416
 
tracebacks::
 
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::
417
452
 
418
453
    debug_flags = hpss, error
419
454
 
430
465
Unicode and Encoding Support
431
466
============================
432
467
 
433
 
This section discusses various techniques that Breezy uses to handle
 
468
This section discusses various techniques that Bazaar uses to handle
434
469
characters that are outside the ASCII set.
435
470
 
436
471
``Command.outf``
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.
455
490
 
456
491
  strict
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.
466
501
  exact
467
502
    Do not attempt to automatically convert Unicode strings. This is used
468
503
    for commands that must handle conversion themselves.
469
 
    For example: ``brz diff`` needs to translate Unicode paths, but should
 
504
    For example: ``bzr diff`` needs to translate Unicode paths, but should
470
505
    not change the exact text of the contents of the files.
471
506
 
472
507
 
485
520
C Extension Modules
486
521
===================
487
522
 
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
489
524
three scenarios:
490
525
 
491
526
 * User with no C compiler
492
527
 * User with C compiler
493
528
 * Developers
494
529
 
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.
498
533
 
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.
501
536
 
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.
505
540
 
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.
512
547
 
 
548
Note that pyrex does not support all 2.4 programming idioms, so some
 
549
syntax changes may be required. I.e.
 
550
 
 
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'
 
553
 
 
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.
 
557
 
 
558
 
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
-------------------------
526
572
 
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:
531
577
 
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>`_)
535
582
 
536
583
.. note::
537
584
  Removing barriers to community participation is a key reason for adopting
558
605
energy by emailing the **bazaar-commits** list implicitly. To do this,
559
606
install and configure the Email plugin. One way to do this is add these
560
607
configuration settings to your central configuration file (e.g.
561
 
``~/.config/breezy/breezy.conf``)::
 
608
``~/.bazaar/bazaar.conf``)::
562
609
 
563
610
  [DEFAULT]
564
611
  email = Joe Smith <joe.smith@internode.on.net>