~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/developer-guide/HACKING.txt

  • Committer: Martin Pool
  • Date: 2009-06-16 04:28:19 UTC
  • mto: This revision was merged to the branch mainline in revision 4464.
  • Revision ID: mbp@sourcefrog.net-20090616042819-adz0sq9ct1ls8rrl
Move tools.doc_generate into bzrlib

Show diffs side-by-side

added added

removed removed

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