~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

  • Committer: John Arbash Meinel
  • Date: 2009-06-19 17:53:37 UTC
  • mto: This revision was merged to the branch mainline in revision 4466.
  • Revision ID: john@arbash-meinel.com-20090619175337-uozt3bntdd48lh4z
Update time_graph to use X:1 ratios rather than 0.xxx ratios.
It is just easier to track now that the new code is much faster.

Show diffs side-by-side

added added

removed removed

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