~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to HACKING

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2006-05-19 06:14:38 UTC
  • mfrom: (1704.2.23 bzr.mbp.integration)
  • Revision ID: pqm@pqm.ubuntu.com-20060519061438-6300caf3926c3cff
(mbp) small fixes

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