/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: Marius Kruger
  • Date: 2010-07-10 21:28:56 UTC
  • mto: (5384.1.1 integration)
  • mto: This revision was merged to the branch mainline in revision 5385.
  • Revision ID: marius.kruger@enerweb.co.za-20100710212856-uq4ji3go0u5se7hx
* Update documentation
* add NEWS

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/HACKING.txt
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
 
.. was from http://wiki.bazaar.canonical.com/BzrGivingBack
 
76
.. was from bazaar-vcs.org/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 http://bazaar-vcs.org/bzr/bzr.dev/ 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 http://bazaar-vcs.org/bzr/bzr.dev/ 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.
240
242
Navigating the Code Base
241
243
========================
242
244
 
243
 
.. Was at <http://wiki.bazaar.canonical.com/NewDeveloperIntroduction>
 
245
.. Was at <http://bazaar-vcs.org/NewDeveloperIntroduction>
244
246
 
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
363
359
can't fix.
364
360
 
365
361
 
 
362
Getting Input
 
363
=============
 
364
 
 
365
Processing Command Lines
 
366
------------------------
 
367
 
 
368
bzrlib has a standard framework for parsing command lines and calling
 
369
processing routines associated with various commands. See builtins.py
 
370
for numerous examples.
 
371
 
 
372
 
 
373
Standard Parameter Types
 
374
------------------------
 
375
 
 
376
There are some common requirements in the library: some parameters need to be
 
377
unicode safe, some need byte strings, and so on. At the moment we have
 
378
only codified one specific pattern: Parameters that need to be unicode
 
379
should be checked via ``bzrlib.osutils.safe_unicode``. This will coerce the
 
380
input into unicode in a consistent fashion, allowing trivial strings to be
 
381
used for programmer convenience, but not performing unpredictably in the
 
382
presence of different locales.
 
383
 
 
384
 
 
385
Writing Output
 
386
==============
 
387
 
 
388
(The strategy described here is what we want to get to, but it's not
 
389
consistently followed in the code at the moment.)
 
390
 
 
391
bzrlib is intended to be a generically reusable library.  It shouldn't
 
392
write messages to stdout or stderr, because some programs that use it
 
393
might want to display that information through a GUI or some other
 
394
mechanism.
 
395
 
 
396
We can distinguish two types of output from the library:
 
397
 
 
398
 1. Structured data representing the progress or result of an
 
399
    operation.  For example, for a commit command this will be a list
 
400
    of the modified files and the finally committed revision number
 
401
    and id.
 
402
 
 
403
    These should be exposed either through the return code or by calls
 
404
    to a callback parameter.
 
405
 
 
406
    A special case of this is progress indicators for long-lived
 
407
    operations, where the caller should pass a ProgressBar object.
 
408
 
 
409
 2. Unstructured log/debug messages, mostly for the benefit of the
 
410
    developers or users trying to debug problems.  This should always
 
411
    be sent through ``bzrlib.trace`` and Python ``logging``, so that
 
412
    it can be redirected by the client.
 
413
 
 
414
The distinction between the two is a bit subjective, but in general if
 
415
there is any chance that a library would want to see something as
 
416
structured data, we should make it so.
 
417
 
 
418
The policy about how output is presented in the text-mode client
 
419
should be only in the command-line tool.
 
420
 
 
421
 
 
422
Progress and Activity Indications
 
423
---------------------------------
 
424
 
 
425
bzrlib has a way for code to display to the user that stuff is happening
 
426
during a long operation.  There are two particular types: *activity* which
 
427
means that IO is happening on a Transport, and *progress* which means that
 
428
higher-level application work is occurring.  Both are drawn together by
 
429
the `ui_factory`.
 
430
 
 
431
Transport objects are responsible for calling `report_transport_activity`
 
432
when they do IO.
 
433
 
 
434
Progress uses a model/view pattern: application code acts on a
 
435
`ProgressTask` object, which notifies the UI when it needs to be
 
436
displayed.  Progress tasks form a stack.  To create a new progress task on
 
437
top of the stack, call `bzrlib.ui.ui_factory.nested_progress_bar()`, then
 
438
call `update()` on the returned ProgressTask.  It can be updated with just
 
439
a text description, with a numeric count, or with a numeric count and
 
440
expected total count.  If an expected total count is provided the view
 
441
can show the progress moving along towards the expected total.
 
442
 
 
443
The user should call `finish` on the `ProgressTask` when the logical
 
444
operation has finished, so it can be removed from the stack.
 
445
 
 
446
Progress tasks have a complex relationship with generators: it's a very
 
447
good place to use them, but because python2.4 does not allow ``finally``
 
448
blocks in generators it's hard to clean them up properly.  In this case
 
449
it's probably better to have the code calling the generator allocate a
 
450
progress task for its use and then call `finalize` when it's done, which
 
451
will close it if it was not already closed.  The generator should also
 
452
finish the progress task when it exits, because it may otherwise be a long
 
453
time until the finally block runs.
 
454
 
 
455
 
 
456
Message guidelines
 
457
------------------
 
458
 
 
459
When filenames or similar variables are presented inline within a message,
 
460
they should be enclosed in double quotes (ascii 0x22, not chiral unicode
 
461
quotes)::
 
462
 
 
463
  bzr: ERROR: No such file "asdf"
 
464
 
 
465
When we print just a list of filenames there should not be any quoting:
 
466
see `bug 544297`_.
 
467
 
 
468
.. _bug 544297: https://bugs.launchpad.net/bugs/544297
 
469
 
 
470
https://wiki.ubuntu.com/UnitsPolicy provides a good explanation about
 
471
which unit should be used when. Roughly speaking, IEC standard applies
 
472
for base-2 units and SI standard applies for base-10 units:
 
473
 
 
474
* for network bandwidth and disk sizes, use base-10 (Mbits/s, kB/s, GB)
 
475
 
 
476
* for RAM sizes, use base-2 (GiB, TiB)
 
477
 
 
478
 
 
479
 
 
480
Displaying help
 
481
===============
 
482
 
 
483
Bazaar has online help for various topics through ``bzr help COMMAND`` or
 
484
equivalently ``bzr command -h``.  We also have help on command options,
 
485
and on other help topics.  (See ``help_topics.py``.)
 
486
 
 
487
As for python docstrings, the first paragraph should be a single-sentence
 
488
synopsis of the command. These are user-visible and should be prefixed with
 
489
``__doc__ =`` so help works under ``python -OO`` with docstrings stripped.
 
490
 
 
491
The help for options should be one or more proper sentences, starting with
 
492
a capital letter and finishing with a full stop (period).
 
493
 
 
494
All help messages and documentation should have two spaces between
 
495
sentences.
 
496
 
 
497
 
 
498
Handling Errors and Exceptions
 
499
==============================
 
500
 
 
501
Commands should return non-zero when they encounter circumstances that
 
502
the user should really pay attention to - which includes trivial shell
 
503
pipelines.
 
504
 
 
505
Recommended values are:
 
506
 
 
507
    0. OK.
 
508
    1. Conflicts in merge-like operations, or changes are present in
 
509
       diff-like operations.
 
510
    2. Unrepresentable diff changes (i.e. binary files that we cannot show
 
511
       a diff of).
 
512
    3. An error or exception has occurred.
 
513
    4. An internal error occurred (one that shows a traceback.)
 
514
 
 
515
Errors are handled through Python exceptions. Exceptions should be defined
 
516
inside bzrlib.errors, so that we can see the whole tree at a glance.
 
517
 
 
518
We broadly classify errors as either being either internal or not,
 
519
depending on whether ``internal_error`` is set or not.  If we think it's our
 
520
fault, we show a backtrace, an invitation to report the bug, and possibly
 
521
other details.  This is the default for errors that aren't specifically
 
522
recognized as being caused by a user error.  Otherwise we show a briefer
 
523
message, unless -Derror was given.
 
524
 
 
525
Many errors originate as "environmental errors" which are raised by Python
 
526
or builtin libraries -- for example IOError.  These are treated as being
 
527
our fault, unless they're caught in a particular tight scope where we know
 
528
that they indicate a user errors.  For example if the repository format
 
529
is not found, the user probably gave the wrong path or URL.  But if one of
 
530
the files inside the repository is not found, then it's our fault --
 
531
either there's a bug in bzr, or something complicated has gone wrong in
 
532
the environment that means one internal file was deleted.
 
533
 
 
534
Many errors are defined in ``bzrlib/errors.py`` but it's OK for new errors
 
535
to be added near the place where they are used.
 
536
 
 
537
Exceptions are formatted for the user by conversion to a string
 
538
(eventually calling their ``__str__`` method.)  As a convenience the
 
539
``._fmt`` member can be used as a template which will be mapped to the
 
540
error's instance dict.
 
541
 
 
542
New exception classes should be defined when callers might want to catch
 
543
that exception specifically, or when it needs a substantially different
 
544
format string.
 
545
 
 
546
#. If it is something that a caller can recover from, a custom exception
 
547
   is reasonable.
 
548
 
 
549
#. If it is a data consistency issue, using a builtin like
 
550
   ``ValueError``/``TypeError`` is reasonable.
 
551
 
 
552
#. If it is a programmer error (using an api incorrectly)
 
553
   ``AssertionError`` is reasonable.
 
554
 
 
555
#. Otherwise, use ``BzrError`` or ``InternalBzrError``.
 
556
 
 
557
Exception strings should start with a capital letter and should not have a
 
558
final fullstop.  If long, they may contain newlines to break the text.
 
559
 
 
560
 
 
561
 
 
562
Documenting Changes
 
563
===================
 
564
 
 
565
When you change bzrlib, please update the relevant documentation for the
 
566
change you made: Changes to commands should update their help, and
 
567
possibly end user tutorials; changes to the core library should be
 
568
reflected in API documentation.
 
569
 
 
570
NEWS File
 
571
---------
 
572
 
 
573
If you make a user-visible change, please add a note to the NEWS file.
 
574
The description should be written to make sense to someone who's just
 
575
a user of bzr, not a developer: new functions or classes shouldn't be
 
576
mentioned, but new commands, changes in behaviour or fixed nontrivial
 
577
bugs should be listed.  See the existing entries for an idea of what
 
578
should be done.
 
579
 
 
580
Within each release, entries in the news file should have the most
 
581
user-visible changes first.  So the order should be approximately:
 
582
 
 
583
 * changes to existing behaviour - the highest priority because the
 
584
   user's existing knowledge is incorrect
 
585
 * new features - should be brought to their attention
 
586
 * bug fixes - may be of interest if the bug was affecting them, and
 
587
   should include the bug number if any
 
588
 * major documentation changes, including fixed documentation bugs
 
589
 * changes to internal interfaces
 
590
 
 
591
People who made significant contributions to each change are listed in
 
592
parenthesis.  This can include reporting bugs (particularly with good
 
593
details or reproduction recipes), submitting patches, etc.
 
594
 
 
595
To help with merging, NEWS entries should be sorted lexicographically
 
596
within each section.
 
597
 
 
598
Commands
 
599
--------
 
600
 
 
601
The docstring of a command is used by ``bzr help`` to generate help output
 
602
for the command. The list 'takes_options' attribute on a command is used by
 
603
``bzr help`` to document the options for the command - the command
 
604
docstring does not need to document them. Finally, the '_see_also'
 
605
attribute on a command can be used to reference other related help topics.
 
606
 
 
607
API Documentation
 
608
-----------------
 
609
 
 
610
Functions, methods, classes and modules should have docstrings
 
611
describing how they are used.
 
612
 
 
613
The first line of the docstring should be a self-contained sentence.
 
614
 
 
615
For the special case of Command classes, this acts as the user-visible
 
616
documentation shown by the help command.
 
617
 
 
618
The docstrings should be formatted as reStructuredText_ (like this
 
619
document), suitable for processing using the epydoc_ tool into HTML
 
620
documentation.
 
621
 
 
622
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
 
623
.. _epydoc: http://epydoc.sourceforge.net/
 
624
 
 
625
 
366
626
General Guidelines
367
627
==================
368
628
 
 
629
Copyright
 
630
---------
 
631
 
 
632
The copyright policy for bzr was recently made clear in this email (edited
 
633
for grammatical correctness)::
 
634
 
 
635
    The attached patch cleans up the copyright and license statements in
 
636
    the bzr source. It also adds tests to help us remember to add them
 
637
    with the correct text.
 
638
 
 
639
    We had the problem that lots of our files were "Copyright Canonical
 
640
    Development Ltd" which is not a real company, and some other variations
 
641
    on this theme. Also, some files were missing the GPL statements.
 
642
 
 
643
    I want to be clear about the intent of this patch, since copyright can
 
644
    be a little controversial.
 
645
 
 
646
    1) The big motivation for this is not to shut out the community, but
 
647
    just to clean up all of the invalid copyright statements.
 
648
 
 
649
    2) It has been the general policy for bzr that we want a single
 
650
    copyright holder for all of the core code. This is following the model
 
651
    set by the FSF, which makes it easier to update the code to a new
 
652
    license in case problems are encountered. (For example, if we want to
 
653
    upgrade the project universally to GPL v3 it is much simpler if there is
 
654
    a single copyright holder). It also makes it clearer if copyright is
 
655
    ever debated, there is a single holder, which makes it easier to defend
 
656
    in court, etc. (I think the FSF position is that if you assign them
 
657
    copyright, they can defend it in court rather than you needing to, and
 
658
    I'm sure Canonical would do the same).
 
659
    As such, Canonical has requested copyright assignments from all of the
 
660
    major contributers.
 
661
 
 
662
    3) If someone wants to add code and not attribute it to Canonical, there
 
663
    is a specific list of files that are excluded from this check. And the
 
664
    test failure indicates where that is, and how to update it.
 
665
 
 
666
    4) If anyone feels that I changed a copyright statement incorrectly, just
 
667
    let me know, and I'll be happy to correct it. Whenever you have large
 
668
    mechanical changes like this, it is possible to make some mistakes.
 
669
 
 
670
    Just to reiterate, this is a community project, and it is meant to stay
 
671
    that way. Core bzr code is copyright Canonical for legal reasons, and
 
672
    the tests are just there to help us maintain that.
 
673
 
 
674
 
369
675
Miscellaneous Topics
370
676
####################
371
677
 
372
678
Debugging
373
679
=========
374
680
 
375
 
Breezy has a few facilities to help debug problems by going into pdb_, the
 
681
Bazaar has a few facilities to help debug problems by going into pdb_, the
376
682
Python debugger.
377
683
 
378
684
.. _pdb: http://docs.python.org/lib/debugger-commands.html
379
685
 
380
686
If the ``BZR_PDB`` environment variable is set
381
 
then brz will go into pdb post-mortem mode when an unhandled exception
 
687
then bzr will go into pdb post-mortem mode when an unhandled exception
382
688
occurs.
383
689
 
384
 
If you send a SIGQUIT or SIGBREAK signal to brz then it will drop into the
 
690
If you send a SIGQUIT or SIGBREAK signal to bzr then it will drop into the
385
691
debugger immediately. SIGQUIT can be generated by pressing Ctrl-\\ on
386
692
Unix.  SIGBREAK is generated with Ctrl-Pause on Windows (some laptops have
387
693
this as Fn-Pause).  You can continue execution by typing ``c``.  This can
388
694
be disabled if necessary by setting the environment variable
389
695
``BZR_SIGQUIT_PDB=0``.
390
696
 
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
697
 
398
698
Debug Flags
399
699
===========
400
700
 
401
 
Breezy accepts some global options starting with ``-D`` such as
 
701
Bazaar accepts some global options starting with ``-D`` such as
402
702
``-Dhpss``.  These set a value in `bzrlib.debug.debug_flags`, and
403
703
typically cause more information to be written to the trace file.  Most
404
704
`mutter` calls should be guarded by a check of those flags so that we
406
706
 
407
707
Debug flags may have effects other than just emitting trace messages.
408
708
 
409
 
Run ``brz help global-options`` to see them all.
 
709
Run ``bzr help global-options`` to see them all.
410
710
 
411
711
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::
 
712
``debug_flags`` option in e.g.  ``~/.bazaar/bazaar.conf``.  (Note that it
 
713
must be in this global file, not in the branch or location configuration,
 
714
because it's currently only loaded at startup time.)  For instance you may
 
715
want to always record hpss traces and to see full error tracebacks::
417
716
 
418
717
    debug_flags = hpss, error
419
718
 
430
729
Unicode and Encoding Support
431
730
============================
432
731
 
433
 
This section discusses various techniques that Breezy uses to handle
 
732
This section discusses various techniques that Bazaar uses to handle
434
733
characters that are outside the ASCII set.
435
734
 
436
735
``Command.outf``
450
749
    marker (typically '?'), and no exception will be raised. This is for
451
750
    any command which generates text for the user to review, rather than
452
751
    for automated processing.
453
 
    For example: ``brz log`` should not fail if one of the entries has text
 
752
    For example: ``bzr log`` should not fail if one of the entries has text
454
753
    that cannot be displayed.
455
754
 
456
755
  strict
457
756
    Attempting to print an unprintable character will cause a UnicodeError.
458
757
    This is for commands that are intended more as scripting support, rather
459
758
    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``
 
759
    For example: ``bzr ls`` is designed to be used with shell scripting. One
 
760
    use would be ``bzr ls --null --unknowns | xargs -0 rm``.  If ``bzr``
462
761
    printed a filename with a '?', the wrong file could be deleted. (At the
463
762
    very least, the correct file would not be deleted). An error is used to
464
763
    indicate that the requested action could not be performed.
466
765
  exact
467
766
    Do not attempt to automatically convert Unicode strings. This is used
468
767
    for commands that must handle conversion themselves.
469
 
    For example: ``brz diff`` needs to translate Unicode paths, but should
 
768
    For example: ``bzr diff`` needs to translate Unicode paths, but should
470
769
    not change the exact text of the contents of the files.
471
770
 
472
771
 
476
775
Because Transports work in URLs (as defined earlier), printing the raw URL
477
776
to the user is usually less than optimal. Characters outside the standard
478
777
set are printed as escapes, rather than the real character, and local
479
 
paths would be printed as ``file://`` URLs. The function
 
778
paths would be printed as ``file://`` urls. The function
480
779
``unescape_for_display`` attempts to unescape a URL, such that anything
481
780
that cannot be printed in the current encoding stays an escaped URL, but
482
781
valid characters are generated where possible.
485
784
C Extension Modules
486
785
===================
487
786
 
488
 
We write some extensions in C using Cython. We design these to work in
 
787
We write some extensions in C using pyrex. We design these to work in
489
788
three scenarios:
490
789
 
491
790
 * User with no C compiler
492
791
 * User with C compiler
493
792
 * Developers
494
793
 
495
 
The recommended way to install Breezy is to have a C compiler so that the
 
794
The recommended way to install bzr is to have a C compiler so that the
496
795
extensions can be built, but if no C compiler is present, the pure python
497
796
versions we supply will work, though more slowly.
498
797
 
499
 
For developers we recommend that Cython be installed, so that the C
 
798
For developers we recommend that pyrex be installed, so that the C
500
799
extensions can be changed if needed.
501
800
 
502
801
For the C extensions, the extension module should always match the
503
802
original python one in all respects (modulo speed). This should be
504
803
maintained over time.
505
804
 
506
 
To create an extension, add rules to setup.py for building it with Cython ,
 
805
To create an extension, add rules to setup.py for building it with pyrex,
507
806
and with distutils. Now start with an empty .pyx file. At the top add
508
807
"include 'yourmodule.py'". This will import the contents of foo.py into this
509
808
file at build time - remember that only one module will be loaded at
510
809
runtime. Now you can subclass classes, or replace functions, and only your
511
810
changes need to be present in the .pyx file.
512
811
 
 
812
Note that pyrex does not support all 2.4 programming idioms, so some
 
813
syntax changes may be required. I.e.
 
814
 
 
815
 - 'from foo import (bar, gam)' needs to change to not use the brackets.
 
816
 - 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar'
 
817
 
 
818
If the changes are too dramatic, consider
 
819
maintaining the python code twice - once in the .pyx, and once in the .py,
 
820
and no longer including the .py file.
 
821
 
 
822
 
513
823
Making Installers for OS Windows
514
824
================================
515
825
To build a win32 installer, see the instructions on the wiki page:
524
834
What is a Core Developer?
525
835
-------------------------
526
836
 
527
 
While everyone in the Breezy community is welcome and encouraged to
 
837
While everyone in the Bazaar community is welcome and encouraged to
528
838
propose and submit changes, a smaller team is reponsible for pulling those
529
839
changes together into a cohesive whole. In addition to the general developer
530
840
stuff covered above, "core" developers have responsibility for:
531
841
 
532
842
* reviewing changes
 
843
* reviewing blueprints
533
844
* planning releases
534
 
* managing releases (see `Releasing Breezy <https://www.breezy-vcs.org/developers/releasing.html>`_)
 
845
* managing releases (see `Releasing Bazaar <http://doc.bazaar.canonical.com/developers/releasing.html>`_)
535
846
 
536
847
.. note::
537
848
  Removing barriers to community participation is a key reason for adopting
558
869
energy by emailing the **bazaar-commits** list implicitly. To do this,
559
870
install and configure the Email plugin. One way to do this is add these
560
871
configuration settings to your central configuration file (e.g.
561
 
``~/.config/breezy/breezy.conf``)::
 
872
``~/.bazaar/bazaar.conf``)::
562
873
 
563
874
  [DEFAULT]
564
875
  email = Joe Smith <joe.smith@internode.on.net>