~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/HACKING.txt

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2010-02-01 13:53:24 UTC
  • mfrom: (4990.1.2 rm-obsolete)
  • Revision ID: pqm@pqm.ubuntu.com-20100201135324-cuhuolr97guf5xjp
(Jelmer) Remove obsolete (and broken) biobench and history2revfiles
        tools.

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
======================
 
2
Bazaar Developer Guide
 
3
======================
 
4
 
 
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
 
 
9
If you have any questions or something seems to be incorrect, unclear or
 
10
missing, please talk to us in ``irc://irc.freenode.net/#bzr``, or write to
 
11
the Bazaar mailing list.  To propose a correction or addition to this
 
12
document, send a merge request or new text to the mailing list.
 
13
 
 
14
The latest developer documentation can be found online at
 
15
http://doc.bazaar-vcs.org/developers/.
 
16
 
 
17
 
 
18
Getting Started
 
19
###############
 
20
 
 
21
Exploring the Bazaar Platform
 
22
=============================
 
23
 
 
24
Before making changes, it's a good idea to explore the work already
 
25
done by others. Perhaps the new feature or improvement you're looking
 
26
for is available in another plug-in already? If you find a bug,
 
27
perhaps someone else has already fixed it?
 
28
 
 
29
To answer these questions and more, take a moment to explore the
 
30
overall Bazaar Platform. Here are some links to browse:
 
31
 
 
32
* The Plugins page on the Wiki - http://bazaar-vcs.org/BzrPlugins
 
33
 
 
34
* The Bazaar product family on Launchpad - https://launchpad.net/bazaar
 
35
 
 
36
* Bug Tracker for the core product - https://bugs.launchpad.net/bzr/
 
37
 
 
38
* Blueprint Tracker for the core product - https://blueprints.launchpad.net/bzr/
 
39
 
 
40
If nothing else, perhaps you'll find inspiration in how other developers
 
41
have solved their challenges.
 
42
 
 
43
Finding Something To Do
 
44
=======================
 
45
 
 
46
Ad-hoc performance work can also be done. One useful tool is the 'evil' debug
 
47
flag. For instance running ``bzr -Devil commit -m "test"`` will log a backtrace
 
48
to the bzr log file for every method call which triggers a slow or non-scalable
 
49
part of the bzr library. So checking that a given command with ``-Devil`` has
 
50
no backtraces logged to the log file is a good way to find problem function
 
51
calls that might be nested deep in the code base.
 
52
 
 
53
Planning and Discussing Changes
 
54
===============================
 
55
 
 
56
There is a very active community around Bazaar. Mostly we meet on IRC
 
57
(#bzr on irc.freenode.net) and on the mailing list. To join the Bazaar
 
58
community, see http://bazaar-vcs.org/BzrSupport.
 
59
 
 
60
If you are planning to make a change, it's a very good idea to mention it
 
61
on the IRC channel and/or on the mailing list. There are many advantages
 
62
to involving the community before you spend much time on a change.
 
63
These include:
 
64
 
 
65
* you get to build on the wisdom of others, saving time
 
66
 
 
67
* if others can direct you to similar code, it minimises the work to be done
 
68
 
 
69
* it assists everyone in coordinating direction, priorities and effort.
 
70
 
 
71
In summary, maximising the input from others typically minimises the
 
72
total effort required to get your changes merged. The community is
 
73
friendly, helpful and always keen to welcome newcomers.
 
74
 
 
75
 
 
76
Bazaar Development in a Nutshell
 
77
================================
 
78
 
 
79
.. was from bazaar-vcs.org/BzrGivingBack
 
80
 
 
81
One of the fun things about working on a version control system like Bazaar is
 
82
that the users have a high level of proficiency in contributing back into
 
83
the tool.  Consider the following very brief introduction to contributing back
 
84
to Bazaar.  More detailed instructions are in the following sections.
 
85
 
 
86
Making the change
 
87
-----------------
 
88
 
 
89
First, get a local copy of the development mainline (See `Why make a local
 
90
copy of bzr.dev?`_.)
 
91
::
 
92
 
 
93
 $ bzr init-repo ~/bzr
 
94
 $ cd ~/bzr
 
95
 $ bzr branch http://bazaar-vcs.org/bzr/bzr.dev/ bzr.dev
 
96
 
 
97
Now make your own branch::
 
98
 
 
99
 $ bzr branch bzr.dev 123456-my-bugfix
 
100
 
 
101
This will give you a branch called "123456-my-bugfix" that you can work on
 
102
and commit in. Here, you can study the code, make a fix or a new feature.
 
103
Feel free to commit early and often (after all, it's your branch!).
 
104
 
 
105
Documentation improvements are an easy place to get started giving back to the
 
106
Bazaar project.  The documentation is in the `doc/` subdirectory of the Bazaar
 
107
source tree.
 
108
 
 
109
When you are done, make sure that you commit your last set of changes as well!
 
110
Once you are happy with your changes, ask for them to be merged, as described
 
111
below.
 
112
 
 
113
Making a Merge Proposal
 
114
-----------------------
 
115
 
 
116
The Bazaar developers use Launchpad to further enable a truly distributed
 
117
style of development.  Anyone can propose a branch for merging into the Bazaar
 
118
trunk.  To start this process, you need to push your branch to Launchpad.  To
 
119
do this, you will need a Launchpad account and user name, e.g.
 
120
`your_lp_username`.  You can push your branch to Launchpad directly from
 
121
Bazaar::
 
122
 
 
123
  $ bzr push lp:~your_lp_username/bzr/giveback
 
124
 
 
125
After you have pushed your branch, you will need to propose it for merging to
 
126
the Bazaar trunk.  Go to <https://launchpad.net/your_lp_username/bzr/giveback>
 
127
and choose "Propose for merging into another branch".  Select "~bzr/bzr/trunk"
 
128
to hand your changes off to the Bazaar developers for review and merging.
 
129
 
 
130
Why make a local copy of bzr.dev?
 
131
---------------------------------
 
132
 
 
133
Making a local mirror of bzr.dev is not strictly necessary, but it means
 
134
 
 
135
- You can use that copy of bzr.dev as your main bzr executable, and keep it
 
136
  up-to-date using ``bzr pull``.
 
137
- Certain operations are faster, and can be done when offline.  For example:
 
138
 
 
139
  - ``bzr bundle``
 
140
  - ``bzr diff -r ancestor:...``
 
141
  - ``bzr merge``
 
142
 
 
143
- When it's time to create your next branch, it's more convenient.  When you
 
144
  have further contributions to make, you should do them in their own branch::
 
145
 
 
146
    $ cd ~/bzr
 
147
    $ bzr branch bzr.dev additional_fixes
 
148
    $ cd additional_fixes # hack, hack, hack
 
149
 
 
150
 
 
151
 
 
152
Understanding the Development Process
 
153
=====================================
 
154
 
 
155
The development team follows many practices including:
 
156
 
 
157
* a public roadmap and planning process in which anyone can participate
 
158
 
 
159
* time based milestones everyone can work towards and plan around
 
160
 
 
161
* extensive code review and feedback to contributors
 
162
 
 
163
* complete and rigorous test coverage on any code contributed
 
164
 
 
165
* automated validation that all tests still pass before code is merged
 
166
  into the main code branch.
 
167
 
 
168
The key tools we use to enable these practices are:
 
169
 
 
170
* Launchpad - https://launchpad.net/
 
171
 
 
172
* Bazaar - http://bazaar-vcs.org/
 
173
 
 
174
* Bundle Buggy - http://bundlebuggy.aaronbentley.com/
 
175
 
 
176
* Patch Queue Manager - https://launchpad.net/pqm/
 
177
 
 
178
For further information, see http://bazaar-vcs.org/BzrDevelopment.
 
179
 
 
180
 
 
181
 
 
182
 
 
183
Preparing a Sandbox for Making Changes to Bazaar
 
184
================================================
 
185
 
 
186
Bazaar supports many ways of organising your work. See
 
187
http://bazaar-vcs.org/SharedRepositoryLayouts for a summary of the
 
188
popular alternatives.
 
189
 
 
190
Of course, the best choice for you will depend on numerous factors:
 
191
the number of changes you may be making, the complexity of the changes, etc.
 
192
As a starting suggestion though:
 
193
 
 
194
* create a local copy of the main development branch (bzr.dev) by using
 
195
  this command::
 
196
 
 
197
    bzr branch http://bazaar-vcs.org/bzr/bzr.dev/ bzr.dev
 
198
 
 
199
* keep your copy of bzr.dev pristine (by not developing in it) and keep
 
200
  it up to date (by using bzr pull)
 
201
 
 
202
* create a new branch off your local bzr.dev copy for each issue
 
203
  (bug or feature) you are working on.
 
204
 
 
205
This approach makes it easy to go back and make any required changes
 
206
after a code review. Resubmitting the change is then simple with no
 
207
risk of accidentally including edits related to other issues you may
 
208
be working on. After the changes for an issue are accepted and merged,
 
209
the associated branch can be deleted or archived as you wish.
 
210
 
 
211
 
 
212
Navigating the Code Base
 
213
========================
 
214
 
 
215
.. Was at <http://bazaar-vcs.org/NewDeveloperIntroduction>
 
216
 
 
217
Some of the key files in this directory are:
 
218
 
 
219
bzr
 
220
    The command you run to start Bazaar itself.  This script is pretty
 
221
    short and just does some checks then jumps into bzrlib.
 
222
 
 
223
README
 
224
    This file covers a brief introduction to Bazaar and lists some of its
 
225
    key features.
 
226
 
 
227
NEWS
 
228
    Summary of changes in each Bazaar release that can affect users or
 
229
    plugin developers.
 
230
 
 
231
setup.py
 
232
    Installs Bazaar system-wide or to your home directory.  To perform
 
233
    development work on Bazaar it is not required to run this file - you
 
234
    can simply run the bzr command from the top level directory of your
 
235
    development copy. Note: That if you run setup.py this will create a
 
236
    'build' directory in your development branch. There's nothing wrong
 
237
    with this but don't be confused by it. The build process puts a copy
 
238
    of the main code base into this build directory, along with some other
 
239
    files. You don't need to go in here for anything discussed in this
 
240
    guide.
 
241
 
 
242
bzrlib
 
243
    Possibly the most exciting folder of all, bzrlib holds the main code
 
244
    base. This is where you will go to edit python files and contribute to
 
245
    Bazaar.
 
246
 
 
247
doc
 
248
    Holds documentation on a whole range of things on Bazaar from the
 
249
    origination of ideas within the project to information on Bazaar
 
250
    features and use cases.  Within this directory there is a subdirectory
 
251
    for each translation into a human language.  All the documentation
 
252
    is in the ReStructuredText markup language.
 
253
 
 
254
doc/developers
 
255
    Documentation specifically targeted at Bazaar and plugin developers.
 
256
    (Including this document.)
 
257
 
 
258
 
 
259
 
 
260
Automatically-generated API reference information is available at
 
261
<http://starship.python.net/crew/mwh/bzrlibapi/>.
 
262
 
 
263
See also the `Bazaar Architectural Overview
 
264
<http://doc.bazaar-vcs.org/developers/overview.html>`_.
 
265
 
 
266
 
 
267
The Code Review Process
 
268
#######################
 
269
 
 
270
All code changes coming in to Bazaar are reviewed by someone else.
 
271
Normally changes by core contributors are reviewed by one other core
 
272
developer, and changes from other people are reviewed by two core
 
273
developers.  Use intelligent discretion if the patch is trivial.
 
274
 
 
275
Good reviews do take time. They also regularly require a solid
 
276
understanding of the overall code base. In practice, this means a small
 
277
number of people often have a large review burden - with knowledge comes
 
278
responsibility. No one likes their merge requests sitting in a queue going
 
279
nowhere, so reviewing sooner rather than later is strongly encouraged.
 
280
 
 
281
 
 
282
 
 
283
 
 
284
 
 
285
Review cover letters
 
286
====================
 
287
 
 
288
Please put a "cover letter" on your merge request explaining:
 
289
 
 
290
* the reason **why** you're making this change
 
291
 
 
292
* **how** this change achieves this purpose
 
293
 
 
294
* anything else you may have fixed in passing
 
295
 
 
296
* anything significant that you thought of doing, such as a more
 
297
  extensive fix or a different approach, but didn't or couldn't do now
 
298
 
 
299
A good cover letter makes reviewers' lives easier because they can decide
 
300
from the letter whether they agree with the purpose and approach, and then
 
301
assess whether the patch actually does what the cover letter says.
 
302
Explaining any "drive-by fixes" or roads not taken may also avoid queries
 
303
from the reviewer.  All in all this should give faster and better reviews.
 
304
Sometimes writing the cover letter helps the submitter realize something
 
305
else they need to do.  The size of the cover letter should be proportional
 
306
to the size and complexity of the patch.
 
307
 
 
308
 
 
309
Reviewing proposed changes
 
310
==========================
 
311
 
 
312
Anyone is welcome to review code, and reply to the thread with their
 
313
opinion or comments.
 
314
 
 
315
The simplest way to review a proposed change is to just read the patch on
 
316
the list or in Bundle Buggy.  For more complex changes it may be useful
 
317
to make a new working tree or branch from trunk, and merge the proposed
 
318
change into it, so you can experiment with the code or look at a wider
 
319
context.
 
320
 
 
321
There are three main requirements for code to get in:
 
322
 
 
323
* Doesn't reduce test coverage: if it adds new methods or commands,
 
324
  there should be tests for them.  There is a good test framework
 
325
  and plenty of examples to crib from, but if you are having trouble
 
326
  working out how to test something feel free to post a draft patch
 
327
  and ask for help.
 
328
 
 
329
* Doesn't reduce design clarity, such as by entangling objects
 
330
  we're trying to separate.  This is mostly something the more
 
331
  experienced reviewers need to help check.
 
332
 
 
333
* Improves bugs, features, speed, or code simplicity.
 
334
 
 
335
Code that goes in should not degrade any of these aspects.  Patches are
 
336
welcome that only cleanup the code without changing the external
 
337
behaviour.  The core developers take care to keep the code quality high
 
338
and understandable while recognising that perfect is sometimes the enemy
 
339
of good.
 
340
 
 
341
It is easy for reviews to make people notice other things which should be
 
342
fixed but those things should not hold up the original fix being accepted.
 
343
New things can easily be recorded in the Bug Tracker instead.
 
344
 
 
345
It's normally much easier to review several smaller patches than one large
 
346
one.  You might want to use ``bzr-loom`` to maintain threads of related
 
347
work, or submit a preparatory patch that will make your "real" change
 
348
easier.
 
349
 
 
350
 
 
351
Checklist for reviewers
 
352
=======================
 
353
 
 
354
* Do you understand what the code's doing and why?
 
355
 
 
356
* Will it perform reasonably for large inputs, both in memory size and
 
357
  run time?  Are there some scenarios where performance should be
 
358
  measured?
 
359
 
 
360
* Is it tested, and are the tests at the right level?  Are there both
 
361
  blackbox (command-line level) and API-oriented tests?
 
362
 
 
363
* If this change will be visible to end users or API users, is it
 
364
  appropriately documented in NEWS?
 
365
 
 
366
* Does it meet the coding standards below?
 
367
 
 
368
* If it changes the user-visible behaviour, does it update the help
 
369
  strings and user documentation?
 
370
 
 
371
* If it adds a new major concept or standard practice, does it update the
 
372
  developer documentation?
 
373
 
 
374
* (your ideas here...)
 
375
 
 
376
 
 
377
Reviews on Launchpad
 
378
====================
 
379
 
 
380
From May 2009 on, we prefer people to propose code reviews through
 
381
Launchpad.
 
382
 
 
383
 * <https://launchpad.net/+tour/code-review>
 
384
 
 
385
 * <https://help.launchpad.net/Code/Review>
 
386
 
 
387
Anyone can propose or comment on a merge proposal just by creating a
 
388
Launchpad account.
 
389
 
 
390
There are two ways to create a new merge proposal: through the web
 
391
interface or by email.
 
392
 
 
393
 
 
394
Proposing a merge through the web
 
395
---------------------------------
 
396
 
 
397
To create the proposal through the web, first push your branch to Launchpad.
 
398
For example, a branch dealing with documentation belonging to the Launchpad
 
399
User mbp could be pushed as ::
 
400
 
 
401
  bzr push lp:~mbp/bzr/doc
 
402
 
 
403
Then go to the branch's web page, which in this case would be
 
404
<https://code.launchpad.net/~mbp/bzr/doc>.  You can simplify this step by just
 
405
running ::
 
406
 
 
407
  bzr lp-open
 
408
 
 
409
You can then click "Propose for merging into another branch", and enter your
 
410
cover letter (see above) into the web form.  Typically you'll want to merge
 
411
into ``~bzr/bzr/trunk`` which will be the default; you might also want to
 
412
nominate merging into a release branch for a bug fix.  There is the option to
 
413
specify a specific reviewer or type of review, and you shouldn't normally
 
414
change those.
 
415
 
 
416
Submitting the form takes you to the new page about the merge proposal
 
417
containing the diff of the changes, comments by interested people, and
 
418
controls to comment or vote on the change.
 
419
 
 
420
Proposing a merge by mail
 
421
-------------------------
 
422
 
 
423
To propose a merge by mail, send a bundle to ``merge@code.launchpad.net``.
 
424
 
 
425
You can generate a merge request like this::
 
426
 
 
427
  bzr send -o bug-1234.diff
 
428
 
 
429
``bzr send`` can also send mail directly if you prefer; see the help.
 
430
 
 
431
Reviewing changes
 
432
-----------------
 
433
 
 
434
From <https://code.launchpad.net/bzr/+activereviews> you can see all
 
435
currently active reviews, and choose one to comment on.  This page also
 
436
shows proposals that are now approved and should be merged by someone with
 
437
PQM access.
 
438
 
 
439
 
 
440
Reviews through Bundle Buggy
 
441
============================
 
442
 
 
443
The Bundle Buggy tool used up to May 2009 is still available as a review
 
444
mechanism.
 
445
 
 
446
Sending patches for review
 
447
--------------------------
 
448
 
 
449
If you'd like to propose a change, please post to the
 
450
bazaar@lists.canonical.com list with a bundle, patch, or link to a
 
451
branch. Put ``[PATCH]`` or ``[MERGE]`` in the subject so Bundle Buggy
 
452
can pick it out, and explain the change in the email message text.
 
453
Remember to update the NEWS file as part of your change if it makes any
 
454
changes visible to users or plugin developers. Please include a diff
 
455
against mainline if you're giving a link to a branch.
 
456
 
 
457
You can generate a merge request like this::
 
458
 
 
459
  bzr send -o bug-1234.patch
 
460
 
 
461
A ``.patch`` extension is recommended instead of .bundle as many mail clients
 
462
will send the latter as a binary file.
 
463
 
 
464
``bzr send`` can also send mail directly if you prefer; see the help.
 
465
 
 
466
Please do **NOT** put [PATCH] or [MERGE] in the subject line if you don't
 
467
want it to be merged. If you want comments from developers rather than
 
468
to be merged, you can put ``[RFC]`` in the subject line.
 
469
 
 
470
If this change addresses a bug, please put the bug number in the subject
 
471
line too, in the form ``[#1]`` so that Bundle Buggy can recognize it.
 
472
 
 
473
If the change is intended for a particular release mark that in the
 
474
subject too, e.g. ``[1.6]``.
 
475
Anyone can "vote" on the mailing list by expressing an opinion. Core
 
476
developers can also vote using Bundle Buggy. Here are the voting codes and
 
477
their explanations.
 
478
 
 
479
:approve:  Reviewer wants this submission merged.
 
480
:tweak:    Reviewer wants this submission merged with small changes. (No
 
481
  re-review required.)
 
482
:abstain:  Reviewer does not intend to vote on this patch.
 
483
:resubmit: Please make changes and resubmit for review.
 
484
:reject:   Reviewer doesn't want this kind of change merged.
 
485
:comment:  Not really a vote. Reviewer just wants to comment, for now.
 
486
 
 
487
If a change gets two approvals from core reviewers, and no rejections,
 
488
then it's OK to come in.  Any of the core developers can bring it into the
 
489
bzr.dev trunk and backport it to maintenance branches if required.  The
 
490
Release Manager will merge the change into the branch for a pending
 
491
release, if any. As a guideline, core developers usually merge their own
 
492
changes and volunteer to merge other contributions if they were the second
 
493
reviewer to agree to a change.
 
494
 
 
495
To track the progress of proposed changes, use Bundle Buggy. See
 
496
http://bundlebuggy.aaronbentley.com/help for a link to all the
 
497
outstanding merge requests together with an explanation of the columns.
 
498
Bundle Buggy will also mail you a link to track just your change.
 
499
 
 
500
Coding Style Guidelines
 
501
#######################
 
502
 
 
503
hasattr and getattr
 
504
===================
 
505
 
 
506
``hasattr`` should not be used because it swallows exceptions including
 
507
``KeyboardInterrupt``.  Instead, say something like ::
 
508
 
 
509
  if getattr(thing, 'name', None) is None
 
510
 
 
511
 
 
512
Code layout
 
513
===========
 
514
 
 
515
Please write PEP-8__ compliant code.
 
516
 
 
517
__ http://www.python.org/peps/pep-0008.html
 
518
 
 
519
One often-missed requirement is that the first line of docstrings
 
520
should be a self-contained one-sentence summary.
 
521
 
 
522
We use 4 space indents for blocks, and never use tab characters.  (In vim,
 
523
``set expandtab``.)
 
524
 
 
525
Trailing white space should be avoided, but is allowed.
 
526
You should however not make lots of unrelated white space changes.
 
527
 
 
528
Unix style newlines (LF) are used.
 
529
 
 
530
Each file must have a newline at the end of it.
 
531
 
 
532
Lines should be no more than 79 characters if at all possible.
 
533
Lines that continue a long statement may be indented in either of
 
534
two ways:
 
535
 
 
536
within the parenthesis or other character that opens the block, e.g.::
 
537
 
 
538
    my_long_method(arg1,
 
539
                   arg2,
 
540
                   arg3)
 
541
 
 
542
or indented by four spaces::
 
543
 
 
544
    my_long_method(arg1,
 
545
        arg2,
 
546
        arg3)
 
547
 
 
548
The first is considered clearer by some people; however it can be a bit
 
549
harder to maintain (e.g. when the method name changes), and it does not
 
550
work well if the relevant parenthesis is already far to the right.  Avoid
 
551
this::
 
552
 
 
553
     self.legbone.kneebone.shinbone.toebone.shake_it(one,
 
554
                                                     two,
 
555
                                                     three)
 
556
 
 
557
but rather ::
 
558
 
 
559
     self.legbone.kneebone.shinbone.toebone.shake_it(one,
 
560
         two,
 
561
         three)
 
562
 
 
563
or ::
 
564
 
 
565
     self.legbone.kneebone.shinbone.toebone.shake_it(
 
566
         one, two, three)
 
567
 
 
568
For long lists, we like to add a trailing comma and put the closing
 
569
character on the following line.  This makes it easier to add new items in
 
570
future::
 
571
 
 
572
    from bzrlib.goo import (
 
573
        jam,
 
574
        jelly,
 
575
        marmalade,
 
576
        )
 
577
 
 
578
There should be spaces between function parameters, but not between the
 
579
keyword name and the value::
 
580
 
 
581
    call(1, 3, cheese=quark)
 
582
 
 
583
In emacs::
 
584
 
 
585
    ;(defface my-invalid-face
 
586
    ;  '((t (:background "Red" :underline t)))
 
587
    ;  "Face used to highlight invalid constructs or other uglyties"
 
588
    ;  )
 
589
 
 
590
    (defun my-python-mode-hook ()
 
591
     ;; setup preferred indentation style.
 
592
     (setq fill-column 79)
 
593
     (setq indent-tabs-mode nil) ; no tabs, never, I will not repeat
 
594
    ;  (font-lock-add-keywords 'python-mode
 
595
    ;                         '(("^\\s *\t" . 'my-invalid-face) ; Leading tabs
 
596
    ;                            ("[ \t]+$" . 'my-invalid-face)  ; Trailing spaces
 
597
    ;                            ("^[ \t]+$" . 'my-invalid-face)); Spaces only
 
598
    ;                          )
 
599
     )
 
600
 
 
601
    (add-hook 'python-mode-hook 'my-python-mode-hook)
 
602
 
 
603
The lines beginning with ';' are comments. They can be activated
 
604
if one want to have a strong notice of some tab/space usage
 
605
violations.
 
606
 
 
607
 
 
608
Module Imports
 
609
==============
 
610
 
 
611
* Imports should be done at the top-level of the file, unless there is
 
612
  a strong reason to have them lazily loaded when a particular
 
613
  function runs.  Import statements have a cost, so try to make sure
 
614
  they don't run inside hot functions.
 
615
 
 
616
* Module names should always be given fully-qualified,
 
617
  i.e. ``bzrlib.hashcache`` not just ``hashcache``.
 
618
 
 
619
 
 
620
Naming
 
621
======
 
622
 
 
623
Functions, methods or members that are relatively private are given
 
624
a leading underscore prefix.  Names without a leading underscore are
 
625
public not just across modules but to programmers using bzrlib as an
 
626
API.
 
627
 
 
628
We prefer class names to be concatenated capital words (``TestCase``)
 
629
and variables, methods and functions to be lowercase words joined by
 
630
underscores (``revision_id``, ``get_revision``).
 
631
 
 
632
For the purposes of naming some names are treated as single compound
 
633
words: "filename", "revno".
 
634
 
 
635
Consider naming classes as nouns and functions/methods as verbs.
 
636
 
 
637
Try to avoid using abbreviations in names, because there can be
 
638
inconsistency if other people use the full name.
 
639
 
 
640
 
 
641
Standard Names
 
642
==============
 
643
 
 
644
``revision_id`` not ``rev_id`` or ``revid``
 
645
 
 
646
Functions that transform one thing to another should be named ``x_to_y``
 
647
(not ``x2y`` as occurs in some old code.)
 
648
 
 
649
 
 
650
Destructors
 
651
===========
 
652
 
 
653
Python destructors (``__del__``) work differently to those of other
 
654
languages.  In particular, bear in mind that destructors may be called
 
655
immediately when the object apparently becomes unreferenced, or at some
 
656
later time, or possibly never at all.  Therefore we have restrictions on
 
657
what can be done inside them.
 
658
 
 
659
 0. If you think you need to use a ``__del__`` method ask another
 
660
    developer for alternatives.  If you do need to use one, explain
 
661
    why in a comment.
 
662
 
 
663
 1. Never rely on a ``__del__`` method running.  If there is code that
 
664
    must run, do it from a ``finally`` block instead.
 
665
 
 
666
 2. Never ``import`` from inside a ``__del__`` method, or you may crash the
 
667
    interpreter!!
 
668
 
 
669
 3. In some places we raise a warning from the destructor if the object
 
670
    has not been cleaned up or closed.  This is considered OK: the warning
 
671
    may not catch every case but it's still useful sometimes.
 
672
 
 
673
 
 
674
Cleanup methods
 
675
===============
 
676
 
 
677
Often when something has failed later code, including cleanups invoked
 
678
from ``finally`` blocks, will fail too.  These secondary failures are
 
679
generally uninteresting compared to the original exception.  So use the
 
680
``only_raises`` decorator (from ``bzrlib.decorators``) for methods that
 
681
are typically called in ``finally`` blocks, such as ``unlock`` methods.
 
682
For example, ``@only_raises(LockNotHeld, LockBroken)``.  All errors that
 
683
are unlikely to be a knock-on failure from a previous failure should be
 
684
allowed.
 
685
 
 
686
 
 
687
Factories
 
688
=========
 
689
 
 
690
In some places we have variables which point to callables that construct
 
691
new instances.  That is to say, they can be used a lot like class objects,
 
692
but they shouldn't be *named* like classes:
 
693
 
 
694
> I think that things named FooBar should create instances of FooBar when
 
695
> called. Its plain confusing for them to do otherwise. When we have
 
696
> something that is going to be used as a class - that is, checked for via
 
697
> isinstance or other such idioms, them I would call it foo_class, so that
 
698
> it is clear that a callable is not sufficient. If it is only used as a
 
699
> factory, then yes, foo_factory is what I would use.
 
700
 
 
701
 
 
702
Registries
 
703
==========
 
704
 
 
705
Several places in Bazaar use (or will use) a registry, which is a
 
706
mapping from names to objects or classes.  The registry allows for
 
707
loading in registered code only when it's needed, and keeping
 
708
associated information such as a help string or description.
 
709
 
 
710
 
 
711
InterObject and multiple dispatch
 
712
=================================
 
713
 
 
714
The ``InterObject`` provides for two-way `multiple dispatch`__: matching
 
715
up for example a source and destination repository to find the right way
 
716
to transfer data between them.
 
717
 
 
718
.. __: http://en.wikipedia.org/wiki/Multiple_dispatch
 
719
 
 
720
There is a subclass ``InterObject`` classes for each type of object that is
 
721
dispatched this way, e.g. ``InterRepository``.  Calling ``.get()`` on this
 
722
class will return an ``InterObject`` instance providing the best match for
 
723
those parameters, and this instance then has methods for operations
 
724
between the objects.
 
725
 
 
726
  inter = InterRepository.get(source_repo, target_repo)
 
727
  inter.fetch(revision_id)
 
728
 
 
729
``InterRepository`` also acts as a registry-like object for its
 
730
subclasses, and they can be added through ``.register_optimizer``.  The
 
731
right one to run is selected by asking each class, in reverse order of
 
732
registration, whether it ``.is_compatible`` with the relevant objects.
 
733
 
 
734
Lazy Imports
 
735
============
 
736
 
 
737
To make startup time faster, we use the ``bzrlib.lazy_import`` module to
 
738
delay importing modules until they are actually used. ``lazy_import`` uses
 
739
the same syntax as regular python imports. So to import a few modules in a
 
740
lazy fashion do::
 
741
 
 
742
  from bzrlib.lazy_import import lazy_import
 
743
  lazy_import(globals(), """
 
744
  import os
 
745
  import subprocess
 
746
  import sys
 
747
  import time
 
748
 
 
749
  from bzrlib import (
 
750
     errors,
 
751
     transport,
 
752
     revision as _mod_revision,
 
753
     )
 
754
  import bzrlib.transport
 
755
  import bzrlib.xml5
 
756
  """)
 
757
 
 
758
At this point, all of these exist as a ``ImportReplacer`` object, ready to
 
759
be imported once a member is accessed. Also, when importing a module into
 
760
the local namespace, which is likely to clash with variable names, it is
 
761
recommended to prefix it as ``_mod_<module>``. This makes it clearer that
 
762
the variable is a module, and these object should be hidden anyway, since
 
763
they shouldn't be imported into other namespaces.
 
764
 
 
765
While it is possible for ``lazy_import()`` to import members of a module
 
766
when using the ``from module import member`` syntax, it is recommended to
 
767
only use that syntax to load sub modules ``from module import submodule``.
 
768
This is because variables and classes can frequently be used without
 
769
needing a sub-member for example::
 
770
 
 
771
  lazy_import(globals(), """
 
772
  from module import MyClass
 
773
  """)
 
774
 
 
775
  def test(x):
 
776
      return isinstance(x, MyClass)
 
777
 
 
778
This will incorrectly fail, because ``MyClass`` is a ``ImportReplacer``
 
779
object, rather than the real class.
 
780
 
 
781
It also is incorrect to assign ``ImportReplacer`` objects to other variables.
 
782
Because the replacer only knows about the original name, it is unable to
 
783
replace other variables. The ``ImportReplacer`` class will raise an
 
784
``IllegalUseOfScopeReplacer`` exception if it can figure out that this
 
785
happened. But it requires accessing a member more than once from the new
 
786
variable, so some bugs are not detected right away.
 
787
 
 
788
 
 
789
The Null revision
 
790
=================
 
791
 
 
792
The null revision is the ancestor of all revisions.  Its revno is 0, its
 
793
revision-id is ``null:``, and its tree is the empty tree.  When referring
 
794
to the null revision, please use ``bzrlib.revision.NULL_REVISION``.  Old
 
795
code sometimes uses ``None`` for the null revision, but this practice is
 
796
being phased out.
 
797
 
 
798
 
 
799
Object string representations
 
800
=============================
 
801
 
 
802
Python prints objects using their ``__repr__`` method when they are
 
803
written to logs, exception tracebacks, or the debugger.  We want
 
804
objects to have useful representations to help in determining what went
 
805
wrong.
 
806
 
 
807
If you add a new class you should generally add a ``__repr__`` method
 
808
unless there is an adequate method in a parent class.  There should be a
 
809
test for the repr.
 
810
 
 
811
Representations should typically look like Python constructor syntax, but
 
812
they don't need to include every value in the object and they don't need
 
813
to be able to actually execute.  They're to be read by humans, not
 
814
machines.  Don't hardcode the classname in the format, so that we get the
 
815
correct value if the method is inherited by a subclass.  If you're
 
816
printing attributes of the object, including strings, you should normally
 
817
use ``%r`` syntax (to call their repr in turn).
 
818
 
 
819
Try to avoid the representation becoming more than one or two lines long.
 
820
(But balance this against including useful information, and simplicity of
 
821
implementation.)
 
822
 
 
823
Because repr methods are often called when something has already gone
 
824
wrong, they should be written somewhat more defensively than most code.
 
825
The object may be half-initialized or in some other way in an illegal
 
826
state.  The repr method shouldn't raise an exception, or it may hide the
 
827
(probably more useful) underlying exception.
 
828
 
 
829
Example::
 
830
 
 
831
    def __repr__(self):
 
832
        return '%s(%r)' % (self.__class__.__name__,
 
833
                           self._transport)
 
834
 
 
835
 
 
836
Exception handling
 
837
==================
 
838
 
 
839
A bare ``except`` statement will catch all exceptions, including ones that
 
840
really should terminate the program such as ``MemoryError`` and
 
841
``KeyboardInterrupt``.  They should rarely be used unless the exception is
 
842
later re-raised.  Even then, think about whether catching just
 
843
``Exception`` (which excludes system errors in Python2.5 and later) would
 
844
be better.
 
845
 
 
846
 
 
847
Test coverage
 
848
=============
 
849
 
 
850
All code should be exercised by the test suite.  See the `Bazaar Testing
 
851
Guide <http://doc.bazaar-vcs.org/developers/testing.html>`_ for detailed
 
852
information about writing tests.
 
853
 
 
854
 
 
855
Core Topics
 
856
###########
 
857
 
 
858
Evolving Interfaces
 
859
===================
 
860
 
 
861
We don't change APIs in stable branches: any supported symbol in a stable
 
862
release of bzr must not be altered in any way that would result in
 
863
breaking existing code that uses it. That means that method names,
 
864
parameter ordering, parameter names, variable and attribute names etc must
 
865
not be changed without leaving a 'deprecated forwarder' behind. This even
 
866
applies to modules and classes.
 
867
 
 
868
If you wish to change the behaviour of a supported API in an incompatible
 
869
way, you need to change its name as well. For instance, if I add an optional keyword
 
870
parameter to branch.commit - that's fine. On the other hand, if I add a
 
871
keyword parameter to branch.commit which is a *required* transaction
 
872
object, I should rename the API - i.e. to 'branch.commit_transaction'.
 
873
 
 
874
  (Actually, that may break code that provides a new implementation of
 
875
  ``commit`` and doesn't expect to receive the parameter.)
 
876
 
 
877
When renaming such supported API's, be sure to leave a deprecated_method (or
 
878
_function or ...) behind which forwards to the new API. See the
 
879
bzrlib.symbol_versioning module for decorators that take care of the
 
880
details for you - such as updating the docstring, and issuing a warning
 
881
when the old API is used.
 
882
 
 
883
For unsupported API's, it does not hurt to follow this discipline, but it's
 
884
not required. Minimally though, please try to rename things so that
 
885
callers will at least get an AttributeError rather than weird results.
 
886
 
 
887
 
 
888
Deprecation decorators
 
889
----------------------
 
890
 
 
891
``bzrlib.symbol_versioning`` provides decorators that can be attached to
 
892
methods, functions, and other interfaces to indicate that they should no
 
893
longer be used.  For example::
 
894
 
 
895
   @deprecated_method(deprecated_in((0, 1, 4)))
 
896
   def foo(self):
 
897
        return self._new_foo()
 
898
 
 
899
To deprecate a static method you must call ``deprecated_function``
 
900
(**not** method), after the staticmethod call::
 
901
 
 
902
    @staticmethod
 
903
    @deprecated_function(deprecated_in((0, 1, 4)))
 
904
    def create_repository(base, shared=False, format=None):
 
905
 
 
906
When you deprecate an API, you should not just delete its tests, because
 
907
then we might introduce bugs in them.  If the API is still present at all,
 
908
it should still work.  The basic approach is to use
 
909
``TestCase.applyDeprecated`` which in one step checks that the API gives
 
910
the expected deprecation message, and also returns the real result from
 
911
the method, so that tests can keep running.
 
912
 
 
913
Deprecation warnings will be suppressed for final releases, but not for
 
914
development versions or release candidates, or when running ``bzr
 
915
selftest``. This gives developers information about whether their code is
 
916
using deprecated functions, but avoids confusing users about things they
 
917
can't fix.
 
918
 
 
919
 
 
920
Getting Input
 
921
=============
 
922
 
 
923
Processing Command Lines
 
924
------------------------
 
925
 
 
926
bzrlib has a standard framework for parsing command lines and calling
 
927
processing routines associated with various commands. See builtins.py
 
928
for numerous examples.
 
929
 
 
930
 
 
931
Standard Parameter Types
 
932
------------------------
 
933
 
 
934
There are some common requirements in the library: some parameters need to be
 
935
unicode safe, some need byte strings, and so on. At the moment we have
 
936
only codified one specific pattern: Parameters that need to be unicode
 
937
should be checked via ``bzrlib.osutils.safe_unicode``. This will coerce the
 
938
input into unicode in a consistent fashion, allowing trivial strings to be
 
939
used for programmer convenience, but not performing unpredictably in the
 
940
presence of different locales.
 
941
 
 
942
 
 
943
Writing Output
 
944
==============
 
945
 
 
946
(The strategy described here is what we want to get to, but it's not
 
947
consistently followed in the code at the moment.)
 
948
 
 
949
bzrlib is intended to be a generically reusable library.  It shouldn't
 
950
write messages to stdout or stderr, because some programs that use it
 
951
might want to display that information through a GUI or some other
 
952
mechanism.
 
953
 
 
954
We can distinguish two types of output from the library:
 
955
 
 
956
 1. Structured data representing the progress or result of an
 
957
    operation.  For example, for a commit command this will be a list
 
958
    of the modified files and the finally committed revision number
 
959
    and id.
 
960
 
 
961
    These should be exposed either through the return code or by calls
 
962
    to a callback parameter.
 
963
 
 
964
    A special case of this is progress indicators for long-lived
 
965
    operations, where the caller should pass a ProgressBar object.
 
966
 
 
967
 2. Unstructured log/debug messages, mostly for the benefit of the
 
968
    developers or users trying to debug problems.  This should always
 
969
    be sent through ``bzrlib.trace`` and Python ``logging``, so that
 
970
    it can be redirected by the client.
 
971
 
 
972
The distinction between the two is a bit subjective, but in general if
 
973
there is any chance that a library would want to see something as
 
974
structured data, we should make it so.
 
975
 
 
976
The policy about how output is presented in the text-mode client
 
977
should be only in the command-line tool.
 
978
 
 
979
 
 
980
Progress and Activity Indications
 
981
---------------------------------
 
982
 
 
983
bzrlib has a way for code to display to the user that stuff is happening
 
984
during a long operation.  There are two particular types: *activity* which
 
985
means that IO is happening on a Transport, and *progress* which means that
 
986
higher-level application work is occurring.  Both are drawn together by
 
987
the `ui_factory`.
 
988
 
 
989
Transport objects are responsible for calling `report_transport_activity`
 
990
when they do IO.
 
991
 
 
992
Progress uses a model/view pattern: application code acts on a
 
993
`ProgressTask` object, which notifies the UI when it needs to be
 
994
displayed.  Progress tasks form a stack.  To create a new progress task on
 
995
top of the stack, call `bzrlib.ui.ui_factory.nested_progress_bar()`, then
 
996
call `update()` on the returned ProgressTask.  It can be updated with just
 
997
a text description, with a numeric count, or with a numeric count and
 
998
expected total count.  If an expected total count is provided the view
 
999
can show the progress moving along towards the expected total.
 
1000
 
 
1001
The user should call `finish` on the `ProgressTask` when the logical
 
1002
operation has finished, so it can be removed from the stack.
 
1003
 
 
1004
Progress tasks have a complex relationship with generators: it's a very
 
1005
good place to use them, but because python2.4 does not allow ``finally``
 
1006
blocks in generators it's hard to clean them up properly.  In this case
 
1007
it's probably better to have the code calling the generator allocate a
 
1008
progress task for its use and then call `finalize` when it's done, which
 
1009
will close it if it was not already closed.  The generator should also
 
1010
finish the progress task when it exits, because it may otherwise be a long
 
1011
time until the finally block runs.
 
1012
 
 
1013
 
 
1014
Displaying help
 
1015
===============
 
1016
 
 
1017
Bazaar has online help for various topics through ``bzr help COMMAND`` or
 
1018
equivalently ``bzr command -h``.  We also have help on command options,
 
1019
and on other help topics.  (See ``help_topics.py``.)
 
1020
 
 
1021
As for python docstrings, the first paragraph should be a single-sentence
 
1022
synopsis of the command.
 
1023
 
 
1024
The help for options should be one or more proper sentences, starting with
 
1025
a capital letter and finishing with a full stop (period).
 
1026
 
 
1027
All help messages and documentation should have two spaces between
 
1028
sentences.
 
1029
 
 
1030
 
 
1031
Handling Errors and Exceptions
 
1032
==============================
 
1033
 
 
1034
Commands should return non-zero when they encounter circumstances that
 
1035
the user should really pay attention to - which includes trivial shell
 
1036
pipelines.
 
1037
 
 
1038
Recommended values are:
 
1039
 
 
1040
    0. OK.
 
1041
    1. Conflicts in merge-like operations, or changes are present in
 
1042
       diff-like operations.
 
1043
    2. Unrepresentable diff changes (i.e. binary files that we cannot show
 
1044
       a diff of).
 
1045
    3. An error or exception has occurred.
 
1046
    4. An internal error occurred (one that shows a traceback.)
 
1047
 
 
1048
Errors are handled through Python exceptions. Exceptions should be defined
 
1049
inside bzrlib.errors, so that we can see the whole tree at a glance.
 
1050
 
 
1051
We broadly classify errors as either being either internal or not,
 
1052
depending on whether ``internal_error`` is set or not.  If we think it's our
 
1053
fault, we show a backtrace, an invitation to report the bug, and possibly
 
1054
other details.  This is the default for errors that aren't specifically
 
1055
recognized as being caused by a user error.  Otherwise we show a briefer
 
1056
message, unless -Derror was given.
 
1057
 
 
1058
Many errors originate as "environmental errors" which are raised by Python
 
1059
or builtin libraries -- for example IOError.  These are treated as being
 
1060
our fault, unless they're caught in a particular tight scope where we know
 
1061
that they indicate a user errors.  For example if the repository format
 
1062
is not found, the user probably gave the wrong path or URL.  But if one of
 
1063
the files inside the repository is not found, then it's our fault --
 
1064
either there's a bug in bzr, or something complicated has gone wrong in
 
1065
the environment that means one internal file was deleted.
 
1066
 
 
1067
Many errors are defined in ``bzrlib/errors.py`` but it's OK for new errors
 
1068
to be added near the place where they are used.
 
1069
 
 
1070
Exceptions are formatted for the user by conversion to a string
 
1071
(eventually calling their ``__str__`` method.)  As a convenience the
 
1072
``._fmt`` member can be used as a template which will be mapped to the
 
1073
error's instance dict.
 
1074
 
 
1075
New exception classes should be defined when callers might want to catch
 
1076
that exception specifically, or when it needs a substantially different
 
1077
format string.
 
1078
 
 
1079
#. If it is something that a caller can recover from, a custom exception
 
1080
   is reasonable.
 
1081
 
 
1082
#. If it is a data consistency issue, using a builtin like
 
1083
   ``ValueError``/``TypeError`` is reasonable.
 
1084
 
 
1085
#. If it is a programmer error (using an api incorrectly)
 
1086
   ``AssertionError`` is reasonable.
 
1087
 
 
1088
#. Otherwise, use ``BzrError`` or ``InternalBzrError``.
 
1089
 
 
1090
Exception strings should start with a capital letter and should not have a
 
1091
final fullstop.  If long, they may contain newlines to break the text.
 
1092
 
 
1093
 
 
1094
Assertions
 
1095
==========
 
1096
 
 
1097
Do not use the Python ``assert`` statement, either in tests or elsewhere.
 
1098
A source test checks that it is not used.  It is ok to explicitly raise
 
1099
AssertionError.
 
1100
 
 
1101
Rationale:
 
1102
 
 
1103
 * It makes the behaviour vary depending on whether bzr is run with -O
 
1104
   or not, therefore giving a chance for bugs that occur in one case or
 
1105
   the other, several of which have already occurred: assertions with
 
1106
   side effects, code which can't continue unless the assertion passes,
 
1107
   cases where we should give the user a proper message rather than an
 
1108
   assertion failure.
 
1109
 * It's not that much shorter than an explicit if/raise.
 
1110
 * It tends to lead to fuzzy thinking about whether the check is
 
1111
   actually needed or not, and whether it's an internal error or not
 
1112
 * It tends to cause look-before-you-leap patterns.
 
1113
 * It's unsafe if the check is needed to protect the integrity of the
 
1114
   user's data.
 
1115
 * It tends to give poor messages since the developer can get by with
 
1116
   no explanatory text at all.
 
1117
 * We can't rely on people always running with -O in normal use, so we
 
1118
   can't use it for tests that are actually expensive.
 
1119
 * Expensive checks that help developers are better turned on from the
 
1120
   test suite or a -D flag.
 
1121
 * If used instead of ``self.assert*()`` in tests it makes them falsely pass with -O.
 
1122
 
 
1123
 
 
1124
Documenting Changes
 
1125
===================
 
1126
 
 
1127
When you change bzrlib, please update the relevant documentation for the
 
1128
change you made: Changes to commands should update their help, and
 
1129
possibly end user tutorials; changes to the core library should be
 
1130
reflected in API documentation.
 
1131
 
 
1132
NEWS File
 
1133
---------
 
1134
 
 
1135
If you make a user-visible change, please add a note to the NEWS file.
 
1136
The description should be written to make sense to someone who's just
 
1137
a user of bzr, not a developer: new functions or classes shouldn't be
 
1138
mentioned, but new commands, changes in behaviour or fixed nontrivial
 
1139
bugs should be listed.  See the existing entries for an idea of what
 
1140
should be done.
 
1141
 
 
1142
Within each release, entries in the news file should have the most
 
1143
user-visible changes first.  So the order should be approximately:
 
1144
 
 
1145
 * changes to existing behaviour - the highest priority because the
 
1146
   user's existing knowledge is incorrect
 
1147
 * new features - should be brought to their attention
 
1148
 * bug fixes - may be of interest if the bug was affecting them, and
 
1149
   should include the bug number if any
 
1150
 * major documentation changes, including fixed documentation bugs
 
1151
 * changes to internal interfaces
 
1152
 
 
1153
People who made significant contributions to each change are listed in
 
1154
parenthesis.  This can include reporting bugs (particularly with good
 
1155
details or reproduction recipes), submitting patches, etc.
 
1156
 
 
1157
To help with merging, NEWS entries should be sorted lexicographically
 
1158
within each section.
 
1159
 
 
1160
Commands
 
1161
--------
 
1162
 
 
1163
The docstring of a command is used by ``bzr help`` to generate help output
 
1164
for the command. The list 'takes_options' attribute on a command is used by
 
1165
``bzr help`` to document the options for the command - the command
 
1166
docstring does not need to document them. Finally, the '_see_also'
 
1167
attribute on a command can be used to reference other related help topics.
 
1168
 
 
1169
API Documentation
 
1170
-----------------
 
1171
 
 
1172
Functions, methods, classes and modules should have docstrings
 
1173
describing how they are used.
 
1174
 
 
1175
The first line of the docstring should be a self-contained sentence.
 
1176
 
 
1177
For the special case of Command classes, this acts as the user-visible
 
1178
documentation shown by the help command.
 
1179
 
 
1180
The docstrings should be formatted as reStructuredText_ (like this
 
1181
document), suitable for processing using the epydoc_ tool into HTML
 
1182
documentation.
 
1183
 
 
1184
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
 
1185
.. _epydoc: http://epydoc.sourceforge.net/
 
1186
 
 
1187
 
 
1188
General Guidelines
 
1189
==================
 
1190
 
 
1191
Copyright
 
1192
---------
 
1193
 
 
1194
The copyright policy for bzr was recently made clear in this email (edited
 
1195
for grammatical correctness)::
 
1196
 
 
1197
    The attached patch cleans up the copyright and license statements in
 
1198
    the bzr source. It also adds tests to help us remember to add them
 
1199
    with the correct text.
 
1200
 
 
1201
    We had the problem that lots of our files were "Copyright Canonical
 
1202
    Development Ltd" which is not a real company, and some other variations
 
1203
    on this theme. Also, some files were missing the GPL statements.
 
1204
 
 
1205
    I want to be clear about the intent of this patch, since copyright can
 
1206
    be a little controversial.
 
1207
 
 
1208
    1) The big motivation for this is not to shut out the community, but
 
1209
    just to clean up all of the invalid copyright statements.
 
1210
 
 
1211
    2) It has been the general policy for bzr that we want a single
 
1212
    copyright holder for all of the core code. This is following the model
 
1213
    set by the FSF, which makes it easier to update the code to a new
 
1214
    license in case problems are encountered. (For example, if we want to
 
1215
    upgrade the project universally to GPL v3 it is much simpler if there is
 
1216
    a single copyright holder). It also makes it clearer if copyright is
 
1217
    ever debated, there is a single holder, which makes it easier to defend
 
1218
    in court, etc. (I think the FSF position is that if you assign them
 
1219
    copyright, they can defend it in court rather than you needing to, and
 
1220
    I'm sure Canonical would do the same).
 
1221
    As such, Canonical has requested copyright assignments from all of the
 
1222
    major contributers.
 
1223
 
 
1224
    3) If someone wants to add code and not attribute it to Canonical, there
 
1225
    is a specific list of files that are excluded from this check. And the
 
1226
    test failure indicates where that is, and how to update it.
 
1227
 
 
1228
    4) If anyone feels that I changed a copyright statement incorrectly, just
 
1229
    let me know, and I'll be happy to correct it. Whenever you have large
 
1230
    mechanical changes like this, it is possible to make some mistakes.
 
1231
 
 
1232
    Just to reiterate, this is a community project, and it is meant to stay
 
1233
    that way. Core bzr code is copyright Canonical for legal reasons, and
 
1234
    the tests are just there to help us maintain that.
 
1235
 
 
1236
 
 
1237
Miscellaneous Topics
 
1238
####################
 
1239
 
 
1240
Debugging
 
1241
=========
 
1242
 
 
1243
Bazaar has a few facilities to help debug problems by going into pdb_, the
 
1244
Python debugger.
 
1245
 
 
1246
.. _pdb: http://docs.python.org/lib/debugger-commands.html
 
1247
 
 
1248
If the ``BZR_PDB`` environment variable is set
 
1249
then bzr will go into pdb post-mortem mode when an unhandled exception
 
1250
occurs.
 
1251
 
 
1252
If you send a SIGQUIT or SIGBREAK signal to bzr then it will drop into the
 
1253
debugger immediately. SIGQUIT can be generated by pressing Ctrl-\\ on
 
1254
Unix.  SIGBREAK is generated with Ctrl-Pause on Windows (some laptops have
 
1255
this as Fn-Pause).  You can continue execution by typing ``c``.  This can
 
1256
be disabled if necessary by setting the environment variable
 
1257
``BZR_SIGQUIT_PDB=0``.
 
1258
 
 
1259
 
 
1260
Debug Flags
 
1261
===========
 
1262
 
 
1263
Bazaar accepts some global options starting with ``-D`` such as
 
1264
``-Dhpss``.  These set a value in `bzrlib.debug.debug_flags`, and
 
1265
typically cause more information to be written to the trace file.  Most
 
1266
`mutter` calls should be guarded by a check of those flags so that we
 
1267
don't write out too much information if it's not needed.
 
1268
 
 
1269
Debug flags may have effects other than just emitting trace messages.
 
1270
 
 
1271
Run ``bzr help global-options`` to see them all.
 
1272
 
 
1273
These flags may also be set as a comma-separated list in the
 
1274
``debug_flags`` option in e.g.  ``~/.bazaar/bazaar.conf``.  (Note that it
 
1275
must be in this global file, not in the branch or location configuration,
 
1276
because it's currently only loaded at startup time.)  For instance you may
 
1277
want to always record hpss traces and to see full error tracebacks::
 
1278
 
 
1279
    debug_flags = hpss, error
 
1280
 
 
1281
 
 
1282
Jargon
 
1283
======
 
1284
 
 
1285
revno
 
1286
    Integer identifier for a revision on the main line of a branch.
 
1287
    Revision 0 is always the null revision; others are 1-based
 
1288
    indexes into the branch's revision history.
 
1289
 
 
1290
 
 
1291
Unicode and Encoding Support
 
1292
============================
 
1293
 
 
1294
This section discusses various techniques that Bazaar uses to handle
 
1295
characters that are outside the ASCII set.
 
1296
 
 
1297
``Command.outf``
 
1298
----------------
 
1299
 
 
1300
When a ``Command`` object is created, it is given a member variable
 
1301
accessible by ``self.outf``.  This is a file-like object, which is bound to
 
1302
``sys.stdout``, and should be used to write information to the screen,
 
1303
rather than directly writing to ``sys.stdout`` or calling ``print``.
 
1304
This file has the ability to translate Unicode objects into the correct
 
1305
representation, based on the console encoding.  Also, the class attribute
 
1306
``encoding_type`` will effect how unprintable characters will be
 
1307
handled.  This parameter can take one of 3 values:
 
1308
 
 
1309
  replace
 
1310
    Unprintable characters will be represented with a suitable replacement
 
1311
    marker (typically '?'), and no exception will be raised. This is for
 
1312
    any command which generates text for the user to review, rather than
 
1313
    for automated processing.
 
1314
    For example: ``bzr log`` should not fail if one of the entries has text
 
1315
    that cannot be displayed.
 
1316
 
 
1317
  strict
 
1318
    Attempting to print an unprintable character will cause a UnicodeError.
 
1319
    This is for commands that are intended more as scripting support, rather
 
1320
    than plain user review.
 
1321
    For example: ``bzr ls`` is designed to be used with shell scripting. One
 
1322
    use would be ``bzr ls --null --unknowns | xargs -0 rm``.  If ``bzr``
 
1323
    printed a filename with a '?', the wrong file could be deleted. (At the
 
1324
    very least, the correct file would not be deleted). An error is used to
 
1325
    indicate that the requested action could not be performed.
 
1326
 
 
1327
  exact
 
1328
    Do not attempt to automatically convert Unicode strings. This is used
 
1329
    for commands that must handle conversion themselves.
 
1330
    For example: ``bzr diff`` needs to translate Unicode paths, but should
 
1331
    not change the exact text of the contents of the files.
 
1332
 
 
1333
 
 
1334
``bzrlib.urlutils.unescape_for_display``
 
1335
----------------------------------------
 
1336
 
 
1337
Because Transports work in URLs (as defined earlier), printing the raw URL
 
1338
to the user is usually less than optimal. Characters outside the standard
 
1339
set are printed as escapes, rather than the real character, and local
 
1340
paths would be printed as ``file://`` urls. The function
 
1341
``unescape_for_display`` attempts to unescape a URL, such that anything
 
1342
that cannot be printed in the current encoding stays an escaped URL, but
 
1343
valid characters are generated where possible.
 
1344
 
 
1345
 
 
1346
Portability Tips
 
1347
================
 
1348
 
 
1349
The ``bzrlib.osutils`` module has many useful helper functions, including
 
1350
some more portable variants of functions in the standard library.
 
1351
 
 
1352
In particular, don't use ``shutil.rmtree`` unless it's acceptable for it
 
1353
to fail on Windows if some files are readonly or still open elsewhere.
 
1354
Use ``bzrlib.osutils.rmtree`` instead.
 
1355
 
 
1356
 
 
1357
C Extension Modules
 
1358
===================
 
1359
 
 
1360
We write some extensions in C using pyrex. We design these to work in
 
1361
three scenarios:
 
1362
 
 
1363
 * User with no C compiler
 
1364
 * User with C compiler
 
1365
 * Developers
 
1366
 
 
1367
The recommended way to install bzr is to have a C compiler so that the
 
1368
extensions can be built, but if no C compiler is present, the pure python
 
1369
versions we supply will work, though more slowly.
 
1370
 
 
1371
For developers we recommend that pyrex be installed, so that the C
 
1372
extensions can be changed if needed.
 
1373
 
 
1374
For the C extensions, the extension module should always match the
 
1375
original python one in all respects (modulo speed). This should be
 
1376
maintained over time.
 
1377
 
 
1378
To create an extension, add rules to setup.py for building it with pyrex,
 
1379
and with distutils. Now start with an empty .pyx file. At the top add
 
1380
"include 'yourmodule.py'". This will import the contents of foo.py into this
 
1381
file at build time - remember that only one module will be loaded at
 
1382
runtime. Now you can subclass classes, or replace functions, and only your
 
1383
changes need to be present in the .pyx file.
 
1384
 
 
1385
Note that pyrex does not support all 2.4 programming idioms, so some
 
1386
syntax changes may be required. I.e.
 
1387
 
 
1388
 - 'from foo import (bar, gam)' needs to change to not use the brackets.
 
1389
 - 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar'
 
1390
 
 
1391
If the changes are too dramatic, consider
 
1392
maintaining the python code twice - once in the .pyx, and once in the .py,
 
1393
and no longer including the .py file.
 
1394
 
 
1395
 
 
1396
Making Installers for OS Windows
 
1397
================================
 
1398
To build a win32 installer, see the instructions on the wiki page:
 
1399
http://bazaar-vcs.org/BzrWin32Installer
 
1400
 
 
1401
 
 
1402
Core Developer Tasks
 
1403
####################
 
1404
 
 
1405
Overview
 
1406
========
 
1407
 
 
1408
What is a Core Developer?
 
1409
-------------------------
 
1410
 
 
1411
While everyone in the Bazaar community is welcome and encouraged to
 
1412
propose and submit changes, a smaller team is reponsible for pulling those
 
1413
changes together into a cohesive whole. In addition to the general developer
 
1414
stuff covered above, "core" developers have responsibility for:
 
1415
 
 
1416
* reviewing changes
 
1417
* reviewing blueprints
 
1418
* planning releases
 
1419
* managing releases (see `Releasing Bazaar <http://doc.bazaar-vcs.org/developers/releasing.html>`_)
 
1420
 
 
1421
.. note::
 
1422
  Removing barriers to community participation is a key reason for adopting
 
1423
  distributed VCS technology. While DVCS removes many technical barriers,
 
1424
  a small number of social barriers are often necessary instead.
 
1425
  By documenting how the above things are done, we hope to
 
1426
  encourage more people to participate in these activities, keeping the
 
1427
  differences between core and non-core contributors to a minimum.
 
1428
 
 
1429
 
 
1430
Communicating and Coordinating
 
1431
------------------------------
 
1432
 
 
1433
While it has many advantages, one of the challenges of distributed
 
1434
development is keeping everyone else aware of what you're working on.
 
1435
There are numerous ways to do this:
 
1436
 
 
1437
#. Assign bugs to yourself in Launchpad
 
1438
#. Mention it on the mailing list
 
1439
#. Mention it on IRC
 
1440
 
 
1441
As well as the email notifcations that occur when merge requests are sent
 
1442
and reviewed, you can keep others informed of where you're spending your
 
1443
energy by emailing the **bazaar-commits** list implicitly. To do this,
 
1444
install and configure the Email plugin. One way to do this is add these
 
1445
configuration settings to your central configuration file (e.g.
 
1446
``~/.bazaar/bazaar.conf`` on Linux)::
 
1447
 
 
1448
  [DEFAULT]
 
1449
  email = Joe Smith <joe.smith@internode.on.net>
 
1450
  smtp_server = mail.internode.on.net:25
 
1451
 
 
1452
Then add these lines for the relevant branches in ``locations.conf``::
 
1453
 
 
1454
  post_commit_to = bazaar-commits@lists.canonical.com
 
1455
  post_commit_mailer = smtplib
 
1456
 
 
1457
While attending a sprint, RobertCollins' Dbus plugin is useful for the
 
1458
same reason. See the documentation within the plugin for information on
 
1459
how to set it up and configure it.
 
1460
 
 
1461
 
 
1462
Submitting Changes
 
1463
==================
 
1464
 
 
1465
An Overview of PQM
 
1466
------------------
 
1467
 
 
1468
Of the many workflows supported by Bazaar, the one adopted for Bazaar
 
1469
development itself is known as "Decentralized with automatic gatekeeper".
 
1470
To repeat the explanation of this given on
 
1471
http://bazaar-vcs.org/Workflows:
 
1472
 
 
1473
.. pull-quote::
 
1474
  In this workflow, each developer has their own branch or
 
1475
  branches, plus read-only access to the mainline. A software gatekeeper
 
1476
  (e.g. PQM) has commit rights to the main branch. When a developer wants
 
1477
  their work merged, they request the gatekeeper to merge it. The gatekeeper
 
1478
  does a merge, a compile, and runs the test suite. If the code passes, it
 
1479
  is merged into the mainline.
 
1480
 
 
1481
In a nutshell, here's the overall submission process:
 
1482
 
 
1483
#. get your work ready (including review except for trivial changes)
 
1484
#. push to a public location
 
1485
#. ask PQM to merge from that location
 
1486
 
 
1487
.. note::
 
1488
  At present, PQM always takes the changes to merge from a branch
 
1489
  at a URL that can be read by it. For Bazaar, that means a public,
 
1490
  typically http, URL.
 
1491
 
 
1492
As a result, the following things are needed to use PQM for submissions:
 
1493
 
 
1494
#. A publicly available web server
 
1495
#. Your OpenPGP key registered with PQM (contact RobertCollins for this)
 
1496
#. The PQM plugin installed and configured (not strictly required but
 
1497
   highly recommended).
 
1498
 
 
1499
 
 
1500
Selecting a Public Branch Location
 
1501
----------------------------------
 
1502
 
 
1503
If you don't have your own web server running, branches can always be
 
1504
pushed to Launchpad. Here's the process for doing that:
 
1505
 
 
1506
Depending on your location throughout the world and the size of your
 
1507
repository though, it is often quicker to use an alternative public
 
1508
location to Launchpad, particularly if you can set up your own repo and
 
1509
push into that. By using an existing repo, push only needs to send the
 
1510
changes, instead of the complete repository every time. Note that it is
 
1511
easy to register branches in other locations with Launchpad so no benefits
 
1512
are lost by going this way.
 
1513
 
 
1514
.. note::
 
1515
  For Canonical staff, http://people.ubuntu.com/~<user>/ is one
 
1516
  suggestion for public http branches. Contact your manager for information
 
1517
  on accessing this system if required.
 
1518
 
 
1519
It should also be noted that best practice in this area is subject to
 
1520
change as things evolve. For example, once the Bazaar smart server on
 
1521
Launchpad supports server-side branching, the performance situation will
 
1522
be very different to what it is now (Jun 2007).
 
1523
 
 
1524
 
 
1525
Configuring the PQM Plug-In
 
1526
---------------------------
 
1527
 
 
1528
While not strictly required, the PQM plugin automates a few things and
 
1529
reduces the chance of error. Before looking at the plugin, it helps to
 
1530
understand  a little more how PQM operates. Basically, PQM requires an
 
1531
email indicating what you want it to do. The email typically looks like
 
1532
this::
 
1533
 
 
1534
  star-merge source-branch target-branch
 
1535
 
 
1536
For example::
 
1537
 
 
1538
  star-merge http://bzr.arbash-meinel.com/branches/bzr/jam-integration http://bazaar-vcs.org/bzr/bzr.dev
 
1539
 
 
1540
Note that the command needs to be on one line. The subject of the email
 
1541
will be used for the commit message. The email also needs to be ``gpg``
 
1542
signed with a key that PQM accepts.
 
1543
 
 
1544
The advantages of using the PQM plugin are:
 
1545
 
 
1546
#. You can use the config policies to make it easy to set up public
 
1547
   branches, so you don't have to ever type the full paths you want to merge
 
1548
   from or into.
 
1549
 
 
1550
#. It checks to make sure the public branch last revision matches the
 
1551
   local last revision so you are submitting what you think you are.
 
1552
 
 
1553
#. It uses the same public_branch and smtp sending settings as bzr-email,
 
1554
   so if you have one set up, you have the other mostly set up.
 
1555
 
 
1556
#. Thunderbird refuses to not wrap lines, and request lines are usually
 
1557
   pretty long (you have 2 long URLs in there).
 
1558
 
 
1559
Here are sample configuration settings for the PQM plugin. Here are the
 
1560
lines in bazaar.conf::
 
1561
 
 
1562
  [DEFAULT]
 
1563
  email = Joe Smith <joe.smith@internode.on.net>
 
1564
  smtp_server=mail.internode.on.net:25
 
1565
 
 
1566
And here are the lines in ``locations.conf`` (or ``branch.conf`` for
 
1567
dirstate-tags branches)::
 
1568
 
 
1569
  [/home/joe/bzr/my-integration]
 
1570
  push_location = sftp://joe-smith@bazaar.launchpad.net/%7Ejoe-smith/bzr/my-integration/
 
1571
  push_location:policy = norecurse
 
1572
  public_branch = http://bazaar.launchpad.net/~joe-smith/bzr/my-integration/
 
1573
  public_branch:policy = appendpath
 
1574
  pqm_email = Bazaar PQM <pqm@bazaar-vcs.org>
 
1575
  pqm_branch = http://bazaar-vcs.org/bzr/bzr.dev
 
1576
 
 
1577
Note that the push settings will be added by the first ``push`` on
 
1578
a branch. Indeed the preferred way to generate the lines above is to use
 
1579
``push`` with an argument, then copy-and-paste the other lines into
 
1580
the relevant file.
 
1581
 
 
1582
 
 
1583
Submitting a Change
 
1584
-------------------
 
1585
 
 
1586
Here is one possible recipe once the above environment is set up:
 
1587
 
 
1588
#. pull bzr.dev => my-integration
 
1589
#. merge patch => my-integration
 
1590
#. fix up any final merge conflicts (NEWS being the big killer here).
 
1591
#. commit
 
1592
#. push
 
1593
#. pqm-submit
 
1594
 
 
1595
.. note::
 
1596
  The ``push`` step is not required if ``my-integration`` is a checkout of
 
1597
  a public branch.
 
1598
 
 
1599
  Because of defaults, you can type a single message into commit and
 
1600
  pqm-commit will reuse that.
 
1601
 
 
1602
 
 
1603
Tracking Change Acceptance
 
1604
--------------------------
 
1605
 
 
1606
The web interface to PQM is https://pqm.bazaar-vcs.org/. After submitting
 
1607
a change, you can visit this URL to confirm it was received and placed in
 
1608
PQM's queue.
 
1609
 
 
1610
When PQM completes processing a change, an email is sent to you with the
 
1611
results.
 
1612
 
 
1613
 
 
1614
Reviewing Blueprints
 
1615
====================
 
1616
 
 
1617
Blueprint Tracking Using Launchpad
 
1618
----------------------------------
 
1619
 
 
1620
New features typically require a fair amount of discussion, design and
 
1621
debate. For Bazaar, that information is often captured in a so-called
 
1622
"blueprint" on our Wiki. Overall tracking of blueprints and their status
 
1623
is done using Launchpad's relevant tracker,
 
1624
https://blueprints.launchpad.net/bzr/. Once a blueprint for ready for
 
1625
review, please announce it on the mailing list.
 
1626
 
 
1627
Alternatively, send an email beginning with [RFC] with the proposal to the
 
1628
list. In some cases, you may wish to attach proposed code  or a proposed
 
1629
developer document if that best communicates the idea. Debate can then
 
1630
proceed using the normal merge review processes.
 
1631
 
 
1632
 
 
1633
Recording Blueprint Review Feedback
 
1634
-----------------------------------
 
1635
 
 
1636
Unlike its Bug Tracker, Launchpad's Blueprint Tracker doesn't currently
 
1637
(Jun 2007) support a chronological list of comment responses. Review
 
1638
feedback can either be recorded on the Wiki hosting the blueprints or by
 
1639
using Launchpad's whiteboard feature.
 
1640
 
 
1641
 
 
1642
Planning Releases
 
1643
=================
 
1644
 
 
1645
 
 
1646
Using Releases and Milestones in Launchpad
 
1647
------------------------------------------
 
1648
 
 
1649
TODO ... (Exact policies still under discussion)
 
1650
 
 
1651
 
 
1652
Bug Triage
 
1653
----------
 
1654
 
 
1655
Keeping on top of bugs reported is an important part of ongoing release
 
1656
planning. Everyone in the community is welcome and encouraged to raise
 
1657
bugs, confirm bugs raised by others, and nominate a priority. Practically
 
1658
though, a good percentage of bug triage is often done by the core
 
1659
developers, partially because of their depth of product knowledge.
 
1660
 
 
1661
With respect to bug triage, core developers are encouraged to play an
 
1662
active role with particular attention to the following tasks:
 
1663
 
 
1664
* keeping the number of unconfirmed bugs low
 
1665
* ensuring the priorities are generally right (everything as critical - or
 
1666
  medium - is meaningless)
 
1667
* looking out for regressions and turning those around sooner rather than later.
 
1668
 
 
1669
.. note::
 
1670
  As well as prioritizing bugs and nominating them against a
 
1671
  target milestone, Launchpad lets core developers offer to mentor others in
 
1672
  fixing them.
 
1673
 
 
1674
 
 
1675
..
 
1676
   vim: ft=rst tw=74 ai