~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to HACKING

  • Committer: Martin Pool
  • Date: 2005-08-18 07:51:58 UTC
  • Revision ID: mbp@sourcefrog.net-20050818075157-5f69075fa843d558
- add space to store revision-id in weave files

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
======================
2
 
Bazaar Developer Guide
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://doc.bazaar-vcs.org/bzr.dev/hacking.html)
9
 
 
10
 
 
11
 
Getting Started
12
 
###############
13
 
 
14
 
Exploring the Bazaar Platform
15
 
=============================
16
 
 
17
 
Before making changes, it's a good idea to explore the work already
18
 
done by others. Perhaps the new feature or improvement you're looking
19
 
for is available in another plug-in already? If you find a bug,
20
 
perhaps someone else has already fixed it?
21
 
 
22
 
To answer these questions and more, take a moment to explore the
23
 
overall Bazaar Platform. Here are some links to browse:
24
 
 
25
 
* The Plugins page on the Wiki - http://bazaar-vcs.org/BzrPlugins
26
 
 
27
 
* The Bazaar product family on Launchpad - https://launchpad.net/bazaar
28
 
 
29
 
* Bug Tracker for the core product - https://bugs.launchpad.net/bzr/
30
 
 
31
 
* Blueprint Tracker for the core product - https://blueprints.launchpad.net/bzr/
32
 
 
33
 
If nothing else, perhaps you'll find inspiration in how other developers
34
 
have solved their challenges.
35
 
 
36
 
 
37
 
Planning and Discussing Changes
38
 
===============================
39
 
 
40
 
There is a very active community around Bazaar. Mostly we meet on IRC
41
 
(#bzr on irc.freenode.net) and on the mailing list. To join the Bazaar
42
 
community, see http://bazaar-vcs.org/BzrSupport.
43
 
 
44
 
If you are planning to make a change, it's a very good idea to mention it
45
 
on the IRC channel and/or on the mailing list. There are many advantages
46
 
to involving the community before you spend much time on a change.
47
 
These include:
48
 
 
49
 
* you get to build on the wisdom on others, saving time
50
 
 
51
 
* if others can direct you to similar code, it minimises the work to be done 
52
 
 
53
 
* it assists everyone in coordinating direction, priorities and effort.
54
 
 
55
 
In summary, maximising the input from others typically minimises the
56
 
total effort required to get your changes merged. The community is
57
 
friendly, helpful and always keen to welcome newcomers.
58
 
 
59
 
 
60
 
Bazaar Development in a Nutshell
61
 
================================
62
 
 
63
 
Looking for a 10 minute introduction to submitting a change?
64
 
See http://bazaar-vcs.org/BzrGivingBack.
65
 
 
66
 
TODO: Merge that Wiki page into this document.
67
 
 
68
 
 
69
 
Understanding the Development Process
70
 
=====================================
71
 
 
72
 
The development team follows many best-practices including:
73
 
 
74
 
* a public roadmap and planning process in which anyone can participate
75
 
 
76
 
* time based milestones everyone can work towards and plan around
77
 
 
78
 
* extensive code review and feedback to contributors
79
 
 
80
 
* complete and rigorous test coverage on any code contributed
81
 
 
82
 
* automated validation that all tests still pass before code is merged
83
 
  into the main code branch.
84
 
 
85
 
The key tools we use to enable these practices are:
86
 
 
87
 
* Launchpad - https://launchpad.net/
88
 
 
89
 
* Bazaar - http://bazaar-vcs.org/
90
 
 
91
 
* Bundle Buggy - http://bundlebuggy.aaronbentley.com/
92
 
 
93
 
* Patch Queue Manager - https://launchpad.net/pqm/
94
 
 
95
 
For further information, see http://bazaar-vcs.org/BzrDevelopment.
96
 
 
97
 
 
98
 
A Closer Look at the Merge & Review Process
99
 
===========================================
100
 
 
101
 
If you'd like to propose a change, please post to the
102
 
bazaar@lists.canonical.com list with a bundle, patch, or link to a
103
 
branch. Put '[PATCH]' or '[MERGE]' in the subject so Bundle Buggy
104
 
can pick it out, and explain the change in the email message text.
105
 
Remember to update the NEWS file as part of your change if it makes any
106
 
changes visible to users or plugin developers. Please include a diff
107
 
against mainline if you're giving a link to a branch.
108
 
 
109
 
You can generate a bundle like this::
110
 
 
111
 
  bzr bundle > mybundle.patch
112
 
  
113
 
A .patch extension is recommended instead of .bundle as many mail clients
114
 
will send the latter as a binary file. If a bundle would be too long or your
115
 
mailer mangles whitespace (e.g. implicitly converts Unix newlines to DOS
116
 
newlines), use the merge-directive command instead like this::
117
 
 
118
 
  bzr merge-directive http://bazaar-vcs.org http://example.org/my_branch > my_directive.patch
119
 
 
120
 
See the help for details on the arguments to merge-directive.
121
 
 
122
 
Please do **NOT** put [PATCH] or [MERGE] in the subject line if you don't
123
 
want it to be merged. If you want comments from developers rather than
124
 
to be merged, you can put '[RFC]' in the subject line.
125
 
 
126
 
Anyone is welcome to review code.  There are broadly three gates for
127
 
code to get in:
128
 
 
129
 
 * Doesn't reduce test coverage: if it adds new methods or commands,
130
 
   there should be tests for them.  There is a good test framework
131
 
   and plenty of examples to crib from, but if you are having trouble
132
 
   working out how to test something feel free to post a draft patch
133
 
   and ask for help.
134
 
 
135
 
 * Doesn't reduce design clarity, such as by entangling objects
136
 
   we're trying to separate.  This is mostly something the more
137
 
   experienced reviewers need to help check.
138
 
 
139
 
 * Improves bugs, features, speed, or code simplicity.
140
 
 
141
 
Code that goes in should pass all three. The core developers take care
142
 
to keep the code quality high and understandable while recognising that
143
 
perfect is sometimes the enemy of good. (It is easy for reviews to make
144
 
people notice other things which should be fixed but those things should
145
 
not hold up the original fix being accepted. New things can easily be
146
 
recorded in the Bug Tracker instead.)
147
 
 
148
 
Anyone can "vote" on the mailing list. Core developers can also vote using
149
 
Bundle Buggy. Here are the voting codes and their explanations.
150
 
 
151
 
  -1    really don't want it in current form
152
 
  -0    somewhat uncomfortable 
153
 
  +0    comfortable but resubmission after changes requested
154
 
  +1 conditional        good to go after some minor changes
155
 
  +1    good to go
156
 
 
157
 
+1 conditional is used as a way to avoid another submit/review cycle for
158
 
patches that need small changes.
159
 
 
160
 
If a change gets two +1 votes from core reviewers, and no
161
 
vetos, then it's OK to come in.  Any of the core developers can bring it
162
 
into the bzr.dev trunk and backport it to maintenance branches if required.
163
 
The Release Manager will merge the change into the branch for a pending
164
 
release, if any. As a guideline, core developers usually merge their own
165
 
changes and volunteer to merge other contributions if they were the second
166
 
reviewer to agree to a change.
167
 
 
168
 
To track the progress of proposed changes, use Bundle Buggy. See
169
 
http://bundlebuggy.aaronbentley.com/help for a link to all the
170
 
outstanding merge requests together with an explanation of the columns.
171
 
Bundle Buggy will also mail you a link to track just your change.
172
 
 
173
 
 
174
 
Preparing a Sandbox for Making Changes to Bazaar
175
 
================================================
176
 
 
177
 
Bazaar supports many ways of organising your work. See
178
 
http://bazaar-vcs.org/SharedRepositoryLayouts for a summary of the
179
 
popular alternatives.
180
 
 
181
 
Of course, the best choice for you will depend on numerous factors:
182
 
the number of changes you may be making, the complexity of the changes, etc.
183
 
As a starting suggestion though:
184
 
 
185
 
* create a local copy of the main development branch (bzr.dev) by using
186
 
  this command::
187
 
  
188
 
    bzr branch http://bazaar-vcs.org/bzr/bzr.dev/ bzr.dev
189
 
   
190
 
* keep your copy of bzr.dev prestine (by not developing in it) and keep
191
 
  it up to date (by using bzr pull)
192
 
 
193
 
* create a new branch off your local bzr.dev copy for each issue
194
 
  (bug or feature) you are working on.
195
 
 
196
 
This approach makes it easy to go back and make any required changes
197
 
after a code review. Resubmitting the change is then simple with no
198
 
risk of accidentially including edits related to other issues you may
199
 
be working on. After the changes for an issue are accepted and merged,
200
 
the associated branch can be deleted or archived as you wish.
201
 
 
202
 
 
203
 
Navigating the Code Base
204
 
========================
205
 
 
206
 
TODO: List and describe in one line the purpose of each directory
207
 
inside an installation of bzr.
208
 
 
209
 
TODO: Refer to a central location holding an up to date copy of the API
210
 
documentation generated by epydoc, e.g. something like
211
 
http://starship.python.net/crew/mwh/bzrlibapi/bzrlib.html.
212
 
 
213
 
 
214
 
Testing Bazaar
215
 
##############
216
 
 
217
 
The Importance of Testing
218
 
=========================
219
 
 
220
 
Reliability is a critical success factor for any Version Control System.
221
 
We want Bazaar to be highly reliable across multiple platforms while
222
 
evolving over time to meet the needs of its community. 
223
 
 
224
 
In a nutshell, this is want we expect and encourage:
 
1
============================
 
2
guidelines for modifying bzr
 
3
============================
225
4
 
226
5
* New functionality should have test cases.  Preferably write the
227
6
  test before writing the code.
228
7
 
229
8
  In general, you can test at either the command-line level or the
230
 
  internal API level.  See Writing tests below for more detail.
231
 
 
232
 
* Try to practice Test-Driven Development: before fixing a bug, write a
233
 
  test case so that it does not regress.  Similarly for adding a new
234
 
  feature: write a test case for a small version of the new feature before
235
 
  starting on the code itself.  Check the test fails on the old code, then
236
 
  add the feature or fix and check it passes.
237
 
 
238
 
By doing these things, the Bazaar team gets increased confidence that
239
 
changes do what they claim to do, whether provided by the core team or
240
 
by community members. Equally importantly, we can be surer that changes
241
 
down the track do not break new features or bug fixes that you are
242
 
contributing today.
243
 
 
244
 
As of May 2007, Bazaar ships with a test suite containing over 6000 tests
245
 
and growing. We are proud of it and want to remain so. As community
246
 
members, we all benefit from it. Would you trust version control on
247
 
your project to a product *without* a test suite like Bazaar has?
248
 
 
249
 
 
250
 
Running the Test Suite
251
 
======================
252
 
 
253
 
Currently, bzr selftest is used to invoke tests.
254
 
You can provide a pattern argument to run a subset. For example, 
255
 
to run just the blackbox tests, run::
256
 
 
257
 
  ./bzr selftest -v blackbox
258
 
 
259
 
To skip a particular test (or set of tests), use the --exclude option
260
 
(shorthand -x) like so::
261
 
 
262
 
  ./bzr selftest -v -x blackbox  
263
 
 
264
 
To list tests without running them, use the --list-only option like so::
265
 
 
266
 
  ./bzr selftest --list-only
267
 
 
268
 
This option can be combined with other selftest options (like -x) and
269
 
filter patterns to understand their effect.
270
 
 
271
 
 
272
 
Writing Tests
273
 
=============
274
 
 
275
 
In general tests should be placed in a file named test_FOO.py where 
276
 
FOO is the logical thing under test. That file should be placed in the
277
 
tests subdirectory under the package being tested.
278
 
 
279
 
For example, tests for merge3 in bzrlib belong in bzrlib/tests/test_merge3.py.
280
 
See bzrlib/tests/test_sampler.py for a template test script.
281
 
 
282
 
Tests can be written for the UI or for individual areas of the library.
283
 
Choose whichever is appropriate: if adding a new command, or a new command 
284
 
option, then you should be writing a UI test.  If you are both adding UI
285
 
functionality and library functionality, you will want to write tests for 
286
 
both the UI and the core behaviours.  We call UI tests 'blackbox' tests
287
 
and they are found in ``bzrlib/tests/blackbox/*.py``. 
288
 
 
289
 
When writing blackbox tests please honour the following conventions:
290
 
 
291
 
 1. Place the tests for the command 'name' in
292
 
    bzrlib/tests/blackbox/test_name.py. This makes it easy for developers
293
 
    to locate the test script for a faulty command.
294
 
 
295
 
 2. Use the 'self.run_bzr("name")' utility function to invoke the command
296
 
    rather than running bzr in a subprocess or invoking the
297
 
    cmd_object.run() method directly. This is a lot faster than
298
 
    subprocesses and generates the same logging output as running it in a
299
 
    subprocess (which invoking the method directly does not).
300
 
 
301
 
 3. Only test the one command in a single test script. Use the bzrlib 
302
 
    library when setting up tests and when evaluating the side-effects of
303
 
    the command. We do this so that the library api has continual pressure
304
 
    on it to be as functional as the command line in a simple manner, and
305
 
    to isolate knock-on effects throughout the blackbox test suite when a
306
 
    command changes its name or signature. Ideally only the tests for a
307
 
    given command are affected when a given command is changed.
308
 
 
309
 
 4. If you have a test which does actually require running bzr in a
310
 
    subprocess you can use ``run_bzr_subprocess``. By default the spawned
311
 
    process will not load plugins unless ``--allow-plugins`` is supplied.
312
 
 
313
 
 
314
 
Doctests
315
 
--------
316
 
 
317
 
We make selective use of doctests__.  In general they should provide 
318
 
*examples* within the API documentation which can incidentally be tested.  We 
319
 
don't try to test every important case using doctests -- regular Python
320
 
tests are generally a better solution.
321
 
 
322
 
Most of these are in ``bzrlib/doc/api``.  More additions are welcome.
323
 
 
324
 
  __ http://docs.python.org/lib/module-doctest.html
325
 
 
326
 
 
327
 
Skipping tests and test requirements
328
 
------------------------------------
329
 
 
330
 
In our enhancements to unittest we allow for some addition results beyond
331
 
just success or failure.
332
 
 
333
 
If a test can't be run, it can say that it's skipped.  This is typically
334
 
used in parameterized tests - for example if a transport doesn't support
335
 
setting permissions, we'll skip the tests that relating to that.  ::
336
 
 
337
 
    try:
338
 
        return self.branch_format.initialize(repo.bzrdir)
339
 
    except errors.UninitializableFormat:
340
 
        raise tests.TestSkipped('Uninitializable branch format')
341
 
 
342
 
Raising TestSkipped is a good idea when you want to make it clear that the
343
 
test was not run, rather than just returning which makes it look as if it
344
 
was run and passed.
345
 
 
346
 
A subtly different case is a test that should run, but can't run in the
347
 
current environment.  This covers tests that can only run in particular
348
 
operating systems or locales, or that depend on external libraries.  Here
349
 
we want to inform the user that they didn't get full test coverage, but
350
 
they possibly could if they installed more libraries.  These are expressed
351
 
as a dependency on a feature so we can summarise them, and so that the
352
 
test for the feature is done only once.  (For historical reasons, as of
353
 
May 2007 many cases that should depend on features currently raise
354
 
TestSkipped.)  The typical use is::
355
 
 
356
 
    class TestStrace(TestCaseWithTransport):
357
 
 
358
 
        _test_needs_features = [StraceFeature]
359
 
 
360
 
which means all tests in this class need the feature.  The feature itself
361
 
should provide a ``_probe`` method which is called once to determine if
362
 
it's available.
363
 
 
364
 
 
365
 
Known failures
366
 
--------------
367
 
 
368
 
Known failures are when a test exists but we know it currently doesn't
369
 
work, allowing the test suite to still pass.  These should be used with
370
 
care, we don't want a proliferation of quietly broken tests.  It might be
371
 
appropriate to use them if you've committed a test for a bug but not the
372
 
fix for it, or if something works on Unix but not on Windows.
373
 
 
374
 
 
375
 
Testing exceptions and errors
376
 
-----------------------------
377
 
 
378
 
It's important to test handling of errors and exceptions.  Because this
379
 
code is often not hit in ad-hoc testing it can often have hidden bugs --
380
 
it's particularly common to get NameError because the exception code
381
 
references a variable that has since been renamed.
382
 
 
383
 
.. TODO: Something about how to provoke errors in the right way?
384
 
 
385
 
In general we want to test errors at two levels:
386
 
 
387
 
1. A test in ``test_errors.py`` checking that when the exception object is
388
 
   constructed with known parameters it produces an expected string form.
389
 
   This guards against mistakes in writing the format string, or in the
390
 
   ``str`` representations of its parameters.  There should be one for
391
 
   each exception class.
392
 
 
393
 
2. Tests that when an api is called in a particular situation, it raises
394
 
   an error of the expected class.  You should typically use
395
 
   ``assertRaises``, which in the Bazaar test suite returns the exception
396
 
   object to allow you to examine its parameters.  
397
 
 
398
 
In some cases blackbox tests will also want to check error reporting.  But
399
 
it can be difficult to provoke every error through the commandline
400
 
interface, so those tests are only done as needed -- eg in response to a
401
 
particular bug or if the error is reported in an unusual way(?)  Blackbox
402
 
tests should mostly be testing how the command-line interface works, so
403
 
should only test errors if there is something particular to the cli in how
404
 
they're displayed or handled.
405
 
 
406
 
 
407
 
Essential Domain Classes
408
 
########################
409
 
 
410
 
Introducing the Object Model
411
 
============================
412
 
 
413
 
The core domain objects within the bazaar model are:
414
 
 
415
 
* Transport
416
 
 
417
 
* Branch
418
 
 
419
 
* Repository
420
 
 
421
 
* WorkingTree
422
 
 
423
 
Transports are explained below. See http://bazaar-vcs.org/Classes/
424
 
for an introduction to the other key classes.
425
 
 
426
 
Using Transports
427
 
================
428
 
 
429
 
The ``Transport`` layer handles access to local or remote directories.
430
 
Each Transport object acts like a logical connection to a particular
431
 
directory, and it allows various operations on files within it.  You can
432
 
*clone* a transport to get a new Transport connected to a subdirectory or
433
 
parent directory.
434
 
 
435
 
Transports are not used for access to the working tree.  At present
436
 
working trees are always local and they are accessed through the regular
437
 
Python file io mechanisms.
438
 
 
439
 
Filenames vs URLs
440
 
-----------------
441
 
 
442
 
Transports work in URLs.  Take note that URLs are by definition only
443
 
ASCII - the decision of how to encode a Unicode string into a URL must be
444
 
taken at a higher level, typically in the Store.  (Note that Stores also
445
 
escape filenames which cannot be safely stored on all filesystems, but
446
 
this is a different level.)
447
 
 
448
 
The main reason for this is that it's not possible to safely roundtrip a
449
 
URL into Unicode and then back into the same URL.  The URL standard
450
 
gives a way to represent non-ASCII bytes in ASCII (as %-escapes), but
451
 
doesn't say how those bytes represent non-ASCII characters.  (They're not
452
 
guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
453
 
 
454
 
For example if the user enters the url ``http://example/%e0`` there's no
455
 
way to tell whether that character represents "latin small letter a with
456
 
grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2
457
 
or malformed UTF-8.  So we can't convert their URL to Unicode reliably.
458
 
 
459
 
Equally problematic if we're given a url-like string containing non-ascii
460
 
characters (such as the accented a) we can't be sure how to convert that
461
 
to the correct URL, because we don't know what encoding the server expects
462
 
for those characters.  (Although this is not totally reliable we might still
463
 
accept these and assume they should be put into UTF-8.)
464
 
 
465
 
A similar edge case is that the url ``http://foo/sweet%2Fsour`` contains
466
 
one directory component whose name is "sweet/sour".  The escaped slash is
467
 
not a directory separator.  If we try to convert URLs to regular Unicode
468
 
paths this information will be lost.
469
 
 
470
 
This implies that Transports must natively deal with URLs; for simplicity
471
 
they *only* deal with URLs and conversion of other strings to URLs is done
472
 
elsewhere.  Information they return, such as from ``list_dir``, is also in
473
 
the form of URL components.
474
 
 
475
 
 
476
 
Core Topics
477
 
###########
478
 
 
479
 
Evolving Interfaces
480
 
===================
481
 
 
482
 
We have a commitment to 6 months API stability - any supported symbol in a
483
 
release of bzr MUST NOT be altered in any way that would result in
484
 
breaking existing code that uses it. That means that method names,
485
 
parameter ordering, parameter names, variable and attribute names etc must
486
 
not be changed without leaving a 'deprecated forwarder' behind. This even
487
 
applies to modules and classes.
488
 
 
489
 
If you wish to change the behaviour of a supported API in an incompatible
490
 
way, you need to change its name as well. For instance, if I add an optional keyword
491
 
parameter to branch.commit - that's fine. On the other hand, if I add a
492
 
keyword parameter to branch.commit which is a *required* transaction
493
 
object, I should rename the API - i.e. to 'branch.commit_transaction'. 
494
 
 
495
 
When renaming such supported API's, be sure to leave a deprecated_method (or
496
 
_function or ...) behind which forwards to the new API. See the
497
 
bzrlib.symbol_versioning module for decorators that take care of the
498
 
details for you - such as updating the docstring, and issuing a warning
499
 
when the old api is used.
500
 
 
501
 
For unsupported API's, it does not hurt to follow this discipline, but it's
502
 
not required. Minimally though, please try to rename things so that
503
 
callers will at least get an AttributeError rather than weird results.
504
 
 
505
 
 
506
 
Coding Style Guidelines
507
 
=======================
508
 
 
509
 
Please write PEP-8__ compliant code.  
510
 
 
511
 
One often-missed requirement is that the first line of docstrings
512
 
should be a self-contained one-sentence summary.
513
 
 
514
 
__ http://www.python.org/peps/pep-0008.html
515
 
 
516
 
 
517
 
Module Imports
518
 
--------------
 
9
  internal API level.  Choose whichever is appropriate: if adding a
 
10
  new command, or a new command option, then call through run_bzr().
 
11
  It is not necessary to do both.
 
12
 
 
13
* Before fixing a bug, write a test case so that it does not regress.
 
14
 
 
15
* Exceptions should be defined inside bzrlib.errors, so that we can
 
16
  see the whole tree at a glance.
519
17
 
520
18
* Imports should be done at the top-level of the file, unless there is
521
19
  a strong reason to have them lazily loaded when a particular
522
20
  function runs.  Import statements have a cost, so try to make sure
523
21
  they don't run inside hot functions.
524
22
 
 
23
* Please write PEP-8__ compliant code.
 
24
 
 
25
__ http://www.python.org/peps/pep-0008.html
 
26
 
525
27
* Module names should always be given fully-qualified,
526
28
  i.e. ``bzrlib.hashcache`` not just ``hashcache``.
527
29
 
528
30
 
529
 
Naming
530
 
------
531
 
 
532
 
Functions, methods or members that are in some sense "private" are given
533
 
a leading underscore prefix.  This is just a hint that code outside the
534
 
implementation should probably not use that interface.
535
 
 
536
 
We prefer class names to be concatenated capital words (``TestCase``)
537
 
and variables, methods and functions to be lowercase words joined by
538
 
underscores (``revision_id``, ``get_revision``).
539
 
 
540
 
For the purposes of naming some names are treated as single compound
541
 
words: "filename", "revno".
542
 
 
543
 
Consider naming classes as nouns and functions/methods as verbs.
544
 
 
545
 
Try to avoid using abbreviations in names, because there can be
546
 
inconsistency if other people use the full name.
547
 
 
548
 
 
549
 
Standard Names
550
 
--------------
551
 
 
552
 
``revision_id`` not ``rev_id`` or ``revid``
553
 
 
554
 
Functions that transform one thing to another should be named ``x_to_y``
555
 
(not ``x2y`` as occurs in some old code.)
556
 
 
557
 
 
558
 
Destructors
559
 
-----------
560
 
 
561
 
Python destructors (``__del__``) work differently to those of other
562
 
languages.  In particular, bear in mind that destructors may be called
563
 
immediately when the object apparently becomes unreferenced, or at some
564
 
later time, or possibly never at all.  Therefore we have restrictions on
565
 
what can be done inside them.
566
 
 
567
 
 0. Never use a __del__ method without asking Martin/Robert first.
568
 
 
569
 
 1. Never rely on a ``__del__`` method running.  If there is code that
570
 
    must run, do it from a ``finally`` block instead.
571
 
 
572
 
 2. Never ``import`` from inside a ``__del__`` method, or you may crash the
573
 
    interpreter!!
574
 
 
575
 
 3. In some places we raise a warning from the destructor if the object
576
 
    has not been cleaned up or closed.  This is considered OK: the warning
577
 
    may not catch every case but it's still useful sometimes.
578
 
 
579
 
 
580
 
Factories
581
 
---------
582
 
 
583
 
In some places we have variables which point to callables that construct
584
 
new instances.  That is to say, they can be used a lot like class objects,
585
 
but they shouldn't be *named* like classes:
586
 
 
587
 
> I think that things named FooBar should create instances of FooBar when
588
 
> called. Its plain confusing for them to do otherwise. When we have
589
 
> something that is going to be used as a class - that is, checked for via
590
 
> isinstance or other such idioms, them I would call it foo_class, so that
591
 
> it is clear that a callable is not sufficient. If it is only used as a
592
 
> factory, then yes, foo_factory is what I would use.
593
 
 
594
 
 
595
 
Registries
596
 
----------
597
 
 
598
 
Several places in Bazaar use (or will use) a registry, which is a 
599
 
mapping from names to objects or classes.  The registry allows for 
600
 
loading in registered code only when it's needed, and keeping
601
 
associated information such as a help string or description.
602
 
 
603
 
 
604
 
Lazy Imports
605
 
------------
606
 
 
607
 
To make startup time faster, we use the ``bzrlib.lazy_import`` module to
608
 
delay importing modules until they are actually used. ``lazy_import`` uses
609
 
the same syntax as regular python imports. So to import a few modules in a
610
 
lazy fashion do::
611
 
 
612
 
  from bzrlib.lazy_import import lazy_import
613
 
  lazy_import(globals(), """
614
 
  import os
615
 
  import subprocess
616
 
  import sys
617
 
  import time
618
 
 
619
 
  from bzrlib import (
620
 
     errors,
621
 
     transport,
622
 
     revision as _mod_revision,
623
 
     )
624
 
  import bzrlib.transport
625
 
  import bzrlib.xml5
626
 
  """)
627
 
 
628
 
At this point, all of these exist as a ``ImportReplacer`` object, ready to
629
 
be imported once a member is accessed. Also, when importing a module into
630
 
the local namespace, which is likely to clash with variable names, it is
631
 
recommended to prefix it as ``_mod_<module>``. This makes it clearer that
632
 
the variable is a module, and these object should be hidden anyway, since
633
 
they shouldn't be imported into other namespaces.
634
 
 
635
 
 
636
 
Modules versus Members
637
 
~~~~~~~~~~~~~~~~~~~~~~
638
 
 
639
 
While it is possible for ``lazy_import()`` to import members of a module
640
 
when using the ``from module import member`` syntax, it is recommended to
641
 
only use that syntax to load sub modules ``from module import submodule``.
642
 
This is because variables and classes can frequently be used without
643
 
needing a sub-member for example::
644
 
 
645
 
  lazy_import(globals(), """
646
 
  from module import MyClass
647
 
  """)
648
 
 
649
 
  def test(x):
650
 
      return isinstance(x, MyClass)
651
 
 
652
 
This will incorrectly fail, because ``MyClass`` is a ``ImportReplacer``
653
 
object, rather than the real class.
654
 
 
655
 
 
656
 
Passing to Other Variables
657
 
~~~~~~~~~~~~~~~~~~~~~~~~~~
658
 
 
659
 
It also is incorrect to assign ``ImportReplacer`` objects to other variables.
660
 
Because the replacer only knows about the original name, it is unable to
661
 
replace other variables. The ``ImportReplacer`` class will raise an
662
 
``IllegalUseOfScopeReplacer`` exception if it can figure out that this
663
 
happened. But it requires accessing a member more than once from the new
664
 
variable, so some bugs are not detected right away.
665
 
 
666
 
 
667
 
The Null revision
668
 
-----------------
669
 
 
670
 
The null revision is the ancestor of all revisions.  Its revno is 0, its
671
 
revision-id is ``null:``, and its tree is the empty tree.  When referring
672
 
to the null revision, please use ``bzrlib.revision.NULL_REVISION``.  Old
673
 
code sometimes uses ``None`` for the null revision, but this practice is
674
 
being phased out.
675
 
 
676
 
 
677
 
Getting Input
678
 
=============
679
 
 
680
 
Processing Command Lines
681
 
------------------------
682
 
 
683
 
bzrlib has a standard framework for parsing command lines and calling
684
 
processing routines associated with various commands. See builtins.py
685
 
for numerous examples.
686
 
 
687
 
 
688
 
Standard Parameter Types
689
 
------------------------
690
 
 
691
 
There are some common requirements in the library: some parameters need to be
692
 
unicode safe, some need byte strings, and so on. At the moment we have
693
 
only codified one specific pattern: Parameters that need to be unicode
694
 
should be checked via ``bzrlib.osutils.safe_unicode``. This will coerce the
695
 
input into unicode in a consistent fashion, allowing trivial strings to be
696
 
used for programmer convenience, but not performing unpredictably in the
697
 
presence of different locales.
698
 
 
699
 
 
700
 
Writing Output
701
 
==============
702
 
 
703
 
(The strategy described here is what we want to get to, but it's not
704
 
consistently followed in the code at the moment.)
705
 
 
706
 
bzrlib is intended to be a generically reusable library.  It shouldn't
707
 
write messages to stdout or stderr, because some programs that use it
708
 
might want to display that information through a GUI or some other
709
 
mechanism.
710
 
 
711
 
We can distinguish two types of output from the library:
712
 
 
713
 
 1. Structured data representing the progress or result of an
714
 
    operation.  For example, for a commit command this will be a list
715
 
    of the modified files and the finally committed revision number
716
 
    and id.
717
 
 
718
 
    These should be exposed either through the return code or by calls
719
 
    to a callback parameter.
720
 
 
721
 
    A special case of this is progress indicators for long-lived
722
 
    operations, where the caller should pass a ProgressBar object.
723
 
 
724
 
 2. Unstructured log/debug messages, mostly for the benefit of the
725
 
    developers or users trying to debug problems.  This should always
726
 
    be sent through ``bzrlib.trace`` and Python ``logging``, so that
727
 
    it can be redirected by the client.
728
 
 
729
 
The distinction between the two is a bit subjective, but in general if
730
 
there is any chance that a library would want to see something as
731
 
structured data, we should make it so.
732
 
 
733
 
The policy about how output is presented in the text-mode client
734
 
should be only in the command-line tool.
735
 
 
736
 
 
737
 
 
738
 
Displaying help
739
 
===============
740
 
 
741
 
Bazaar has online help for various topics through ``bzr help COMMAND`` or
742
 
equivalently ``bzr command -h``.  We also have help on command options,
743
 
and on other help topics.  (See ``help_topics.py``.)
744
 
 
745
 
As for python docstrings, the first paragraph should be a single-sentence
746
 
synopsis of the command.
747
 
 
748
 
The help for options should be one or more proper sentences, starting with
749
 
a capital letter and finishing with a full stop (period).
750
 
 
751
 
All help messages and documentation should have two spaces between
752
 
sentences.
753
 
 
754
 
 
755
 
Writing tests
756
 
=============
757
 
 
758
 
In general tests should be placed in a file named test_FOO.py where 
759
 
FOO is the logical thing under test. That file should be placed in the
760
 
tests subdirectory under the package being tested.
761
 
 
762
 
For example, tests for merge3 in bzrlib belong in bzrlib/tests/test_merge3.py.
763
 
See bzrlib/tests/test_sampler.py for a template test script.
764
 
 
765
 
Tests can be written for the UI or for individual areas of the library.
766
 
Choose whichever is appropriate: if adding a new command, or a new command 
767
 
option, then you should be writing a UI test.  If you are both adding UI
768
 
functionality and library functionality, you will want to write tests for 
769
 
both the UI and the core behaviours.  We call UI tests 'blackbox' tests
770
 
and they are found in ``bzrlib/tests/blackbox/*.py``. 
771
 
 
772
 
When writing blackbox tests please honour the following conventions:
773
 
 
774
 
 1. Place the tests for the command 'name' in
775
 
    bzrlib/tests/blackbox/test_name.py. This makes it easy for developers
776
 
    to locate the test script for a faulty command.
777
 
 
778
 
 2. Use the 'self.run_bzr("name")' utility function to invoke the command
779
 
    rather than running bzr in a subprocess or invoking the
780
 
    cmd_object.run() method directly. This is a lot faster than
781
 
    subprocesses and generates the same logging output as running it in a
782
 
    subprocess (which invoking the method directly does not).
783
 
 
784
 
 3. Only test the one command in a single test script. Use the bzrlib 
785
 
    library when setting up tests and when evaluating the side-effects of
786
 
    the command. We do this so that the library api has continual pressure
787
 
    on it to be as functional as the command line in a simple manner, and
788
 
    to isolate knock-on effects throughout the blackbox test suite when a
789
 
    command changes its name or signature. Ideally only the tests for a
790
 
    given command are affected when a given command is changed.
791
 
 
792
 
 4. If you have a test which does actually require running bzr in a
793
 
    subprocess you can use ``run_bzr_subprocess``. By default the spawned
794
 
    process will not load plugins unless ``--allow-plugins`` is supplied.
795
 
 
796
 
 
797
 
Test support
798
 
------------
799
 
 
800
 
We have a rich collection of tools to support writing tests. Please use
801
 
them in preference to ad-hoc solutions as they provide portability and
802
 
performance benefits.
803
 
 
804
 
TreeBuilder
805
 
~~~~~~~~~~~
806
 
 
807
 
The ``TreeBuilder`` interface allows the construction of arbitrary trees
808
 
with a declarative interface. A sample session might look like::
809
 
 
810
 
  tree = self.make_branch_and_tree('path')
811
 
  builder = TreeBuilder()
812
 
  builder.start_tree(tree)
813
 
  builder.build(['foo', "bar/", "bar/file"])
814
 
  tree.commit('commit the tree')
815
 
  builder.finish_tree()
816
 
 
817
 
Please see bzrlib.treebuilder for more details.
818
 
 
819
 
BranchBuilder
820
 
~~~~~~~~~~~~~
821
 
 
822
 
The ``BranchBuilder`` interface allows the creation of test branches in a
823
 
quick and easy manner. A sample session::
824
 
 
825
 
  builder = BranchBuilder(self.get_transport().clone('relpath'))
826
 
  builder.build_commit()
827
 
  builder.build_commit()
828
 
  builder.build_commit()
829
 
  branch = builder.get_branch()
830
 
 
831
 
Please see bzrlib.branchbuilder for more details.
832
 
 
833
 
Doctests
834
 
--------
835
 
 
836
 
We make selective use of doctests__.  In general they should provide 
837
 
*examples* within the API documentation which can incidentally be tested.  We 
838
 
don't try to test every important case using doctests -- regular Python
839
 
tests are generally a better solution.
840
 
 
841
 
Most of these are in ``bzrlib/doc/api``.  More additions are welcome.
842
 
 
843
 
  __ http://docs.python.org/lib/module-doctest.html
844
 
 
845
 
 
846
 
Running tests
847
 
=============
848
 
Currently, bzr selftest is used to invoke tests.
849
 
You can provide a pattern argument to run a subset. For example, 
850
 
to run just the blackbox tests, run::
851
 
 
852
 
  ./bzr selftest -v blackbox
853
 
 
854
 
To skip a particular test (or set of tests), use the --exclude option
855
 
(shorthand -x) like so::
856
 
 
857
 
  ./bzr selftest -v -x blackbox  
858
 
 
859
 
To list tests without running them, use the --list-only option like so::
860
 
 
861
 
  ./bzr selftest --list-only
862
 
 
863
 
This option can be combined with other selftest options (like -x) and
864
 
filter patterns to understand their effect.
865
 
 
866
 
 
867
 
Handling Errors and Exceptions
868
 
==============================
869
 
 
870
 
Commands should return non-zero when they encounter circumstances that
871
 
the user should really pay attention to - which includes trivial shell
872
 
pipelines.
873
 
 
874
 
Recommended values are:
875
 
 
876
 
    0. OK.
877
 
    1. Conflicts in merge-like operations, or changes are present in
878
 
       diff-like operations. 
879
 
    2. Unrepresentable diff changes (i.e. binary files that we cannot show 
880
 
       a diff of).
881
 
    3. An error or exception has occurred.
882
 
 
883
 
Errors are handled through Python exceptions. Exceptions should be defined
884
 
inside bzrlib.errors, so that we can see the whole tree at a glance.
885
 
 
886
 
We broadly classify errors as either being either internal or not,
887
 
depending on whether ``internal_error`` is set or not.  If we think it's our
888
 
fault, we show a backtrace, an invitation to report the bug, and possibly
889
 
other details.  This is the default for errors that aren't specifically
890
 
recognized as being caused by a user error.  Otherwise we show a briefer
891
 
message, unless -Derror was given.
892
 
 
893
 
Many errors originate as "environmental errors" which are raised by Python
894
 
or builtin libraries -- for example IOError.  These are treated as being
895
 
our fault, unless they're caught in a particular tight scope where we know
896
 
that they indicate a user errors.  For example if the repository format
897
 
is not found, the user probably gave the wrong path or URL.  But if one of
898
 
the files inside the repository is not found, then it's our fault --
899
 
either there's a bug in bzr, or something complicated has gone wrong in
900
 
the environment that means one internal file was deleted.
901
 
 
902
 
Many errors are defined in ``bzrlib/errors.py`` but it's OK for new errors
903
 
to be added near the place where they are used.
904
 
 
905
 
Exceptions are formatted for the user by conversion to a string
906
 
(eventually calling their ``__str__`` method.)  As a convenience the
907
 
``._fmt`` member can be used as a template which will be mapped to the
908
 
error's instance dict.
909
 
 
910
 
New exception classes should be defined when callers might want to catch
911
 
that exception specifically, or when it needs a substantially different
912
 
format string.
913
 
 
914
 
Exception strings should start with a capital letter and should not have a
915
 
final fullstop.  If long, they may contain newlines to break the text.
916
 
 
917
 
 
918
 
Documenting Changes
919
 
===================
920
 
 
921
 
When you change bzrlib, please update the relevant documentation for the
922
 
change you made: Changes to commands should update their help, and
923
 
possibly end user tutorials; changes to the core library should be
924
 
reflected in API documentation.
925
 
 
926
 
NEWS File
927
 
---------
 
31
 
 
32
Documentation
 
33
=============
 
34
 
 
35
If you change the behaviour of a command, please update its docstring
 
36
in bzrlib/commands.py.  This is displayed by the 'bzr help' command.
928
37
 
929
38
If you make a user-visible change, please add a note to the NEWS file.
930
39
The description should be written to make sense to someone who's just
932
41
mentioned, but new commands, changes in behaviour or fixed nontrivial
933
42
bugs should be listed.  See the existing entries for an idea of what
934
43
should be done.
935
 
 
936
 
Within each release, entries in the news file should have the most
937
 
user-visible changes first.  So the order should be approximately:
938
 
 
939
 
 * changes to existing behaviour - the highest priority because the 
940
 
   user's existing knowledge is incorrect
941
 
 * new features - should be brought to their attention
942
 
 * bug fixes - may be of interest if the bug was affecting them, and
943
 
   should include the bug number if any
944
 
 * major documentation changes
945
 
 * changes to internal interfaces
946
 
 
947
 
People who made significant contributions to each change are listed in
948
 
parenthesis.  This can include reporting bugs (particularly with good
949
 
details or reproduction recipes), submitting patches, etc.
950
 
 
951
 
Commands
952
 
--------
953
 
 
954
 
The docstring of a command is used by ``bzr help`` to generate help output
955
 
for the command. The list 'takes_options' attribute on a command is used by
956
 
``bzr help`` to document the options for the command - the command
957
 
docstring does not need to document them. Finally, the '_see_also'
958
 
attribute on a command can be used to reference other related help topics.
959
 
 
960
 
API Documentation
961
 
-----------------
962
 
 
963
 
Functions, methods, classes and modules should have docstrings
964
 
describing how they are used. 
965
 
 
966
 
The first line of the docstring should be a self-contained sentence.
967
 
 
968
 
For the special case of Command classes, this acts as the user-visible
969
 
documentation shown by the help command.
970
 
 
971
 
The docstrings should be formatted as reStructuredText_ (like this
972
 
document), suitable for processing using the epydoc_ tool into HTML
973
 
documentation.
974
 
 
975
 
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
976
 
.. _epydoc: http://epydoc.sourceforge.net/
977
 
 
978
 
 
979
 
General Guidelines
980
 
==================
981
 
 
982
 
Copyright
983
 
---------
984
 
 
985
 
The copyright policy for bzr was recently made clear in this email (edited
986
 
for grammatical correctness)::
987
 
 
988
 
    The attached patch cleans up the copyright and license statements in
989
 
    the bzr source. It also adds tests to help us remember to add them
990
 
    with the correct text.
991
 
 
992
 
    We had the problem that lots of our files were "Copyright Canonical
993
 
    Development Ltd" which is not a real company, and some other variations
994
 
    on this theme. Also, some files were missing the GPL statements.
995
 
    
996
 
    I want to be clear about the intent of this patch, since copyright can
997
 
    be a little controversial.
998
 
    
999
 
    1) The big motivation for this is not to shut out the community, but
1000
 
    just to clean up all of the invalid copyright statements.
1001
 
    
1002
 
    2) It has been the general policy for bzr that we want a single
1003
 
    copyright holder for all of the core code. This is following the model
1004
 
    set by the FSF, which makes it easier to update the code to a new
1005
 
    license in case problems are encountered. (For example, if we want to
1006
 
    upgrade the project universally to GPL v3 it is much simpler if there is
1007
 
    a single copyright holder). It also makes it clearer if copyright is
1008
 
    ever debated, there is a single holder, which makes it easier to defend
1009
 
    in court, etc. (I think the FSF position is that if you assign them
1010
 
    copyright, they can defend it in court rather than you needing to, and
1011
 
    I'm sure Canonical would do the same).
1012
 
    As such, Canonical has requested copyright assignments from all of the
1013
 
    major contributers.
1014
 
    
1015
 
    3) If someone wants to add code and not attribute it to Canonical, there
1016
 
    is a specific list of files that are excluded from this check. And the
1017
 
    test failure indicates where that is, and how to update it.
1018
 
    
1019
 
    4) If anyone feels that I changed a copyright statement incorrectly, just
1020
 
    let me know, and I'll be happy to correct it. Whenever you have large
1021
 
    mechanical changes like this, it is possible to make some mistakes.
1022
 
    
1023
 
    Just to reiterate, this is a community project, and it is meant to stay
1024
 
    that way. Core bzr code is copyright Canonical for legal reasons, and
1025
 
    the tests are just there to help us maintain that.
1026
 
 
1027
 
 
1028
 
Miscellaneous Topics
1029
 
####################
1030
 
 
1031
 
Debugging
1032
 
=========
1033
 
 
1034
 
Bazaar has a few facilities to help debug problems by going into pdb_, the
1035
 
Python debugger.
1036
 
 
1037
 
.. _pdb: http://docs.python.org/lib/debugger-commands.html
1038
 
 
1039
 
If the ``BZR_PDB`` environment variable is set 
1040
 
then bzr will go into pdb post-mortem mode when an unhandled exception
1041
 
occurs.
1042
 
 
1043
 
If you send a SIGQUIT signal to bzr, which can be done by pressing
1044
 
Ctrl-\\ on Unix, bzr will go into the debugger immediately.  You can
1045
 
continue execution by typing ``c``.  This can be disabled if necessary
1046
 
by setting the environment variable ``BZR_SIGQUIT_PDB=0``.
1047
 
 
1048
 
 
1049
 
Jargon
1050
 
======
1051
 
 
1052
 
revno
1053
 
    Integer identifier for a revision on the main line of a branch.
1054
 
    Revision 0 is always the null revision; others are 1-based
1055
 
    indexes into the branch's revision history.
1056
 
 
1057
 
 
1058
 
Unicode and Encoding Support
1059
 
============================
1060
 
 
1061
 
This section discusses various techniques that Bazaar uses to handle
1062
 
characters that are outside the ASCII set.
1063
 
 
1064
 
``Command.outf``
1065
 
----------------
1066
 
 
1067
 
When a ``Command`` object is created, it is given a member variable
1068
 
accessible by ``self.outf``.  This is a file-like object, which is bound to
1069
 
``sys.stdout``, and should be used to write information to the screen,
1070
 
rather than directly writing to ``sys.stdout`` or calling ``print``.
1071
 
This file has the ability to translate Unicode objects into the correct
1072
 
representation, based on the console encoding.  Also, the class attribute
1073
 
``encoding_type`` will effect how unprintable characters will be
1074
 
handled.  This parameter can take one of 3 values:
1075
 
 
1076
 
  replace
1077
 
    Unprintable characters will be represented with a suitable replacement
1078
 
    marker (typically '?'), and no exception will be raised. This is for
1079
 
    any command which generates text for the user to review, rather than
1080
 
    for automated processing.
1081
 
    For example: ``bzr log`` should not fail if one of the entries has text
1082
 
    that cannot be displayed.
1083
 
  
1084
 
  strict
1085
 
    Attempting to print an unprintable character will cause a UnicodeError.
1086
 
    This is for commands that are intended more as scripting support, rather
1087
 
    than plain user review.
1088
 
    For exampl: ``bzr ls`` is designed to be used with shell scripting. One
1089
 
    use would be ``bzr ls --null --unknows | xargs -0 rm``.  If ``bzr``
1090
 
    printed a filename with a '?', the wrong file could be deleted. (At the
1091
 
    very least, the correct file would not be deleted). An error is used to
1092
 
    indicate that the requested action could not be performed.
1093
 
  
1094
 
  exact
1095
 
    Do not attempt to automatically convert Unicode strings. This is used
1096
 
    for commands that must handle conversion themselves.
1097
 
    For example: ``bzr diff`` needs to translate Unicode paths, but should
1098
 
    not change the exact text of the contents of the files.
1099
 
 
1100
 
 
1101
 
``bzrlib.urlutils.unescape_for_display``
1102
 
----------------------------------------
1103
 
 
1104
 
Because Transports work in URLs (as defined earlier), printing the raw URL
1105
 
to the user is usually less than optimal. Characters outside the standard
1106
 
set are printed as escapes, rather than the real character, and local
1107
 
paths would be printed as ``file://`` urls. The function
1108
 
``unescape_for_display`` attempts to unescape a URL, such that anything
1109
 
that cannot be printed in the current encoding stays an escaped URL, but
1110
 
valid characters are generated where possible.
1111
 
 
1112
 
 
1113
 
Portability Tips
1114
 
================
1115
 
 
1116
 
The ``bzrlib.osutils`` module has many useful helper functions, including
1117
 
some more portable variants of functions in the standard library.
1118
 
 
1119
 
In particular, don't use ``shutil.rmtree`` unless it's acceptable for it
1120
 
to fail on Windows if some files are readonly or still open elsewhere.
1121
 
Use ``bzrlib.osutils.rmtree`` instead.
1122
 
 
1123
 
 
1124
 
C Extension Modules
1125
 
===================
1126
 
 
1127
 
We write some extensions in C using pyrex. We design these to work in
1128
 
three scenarios:
1129
 
 
1130
 
 * User with no C compiler
1131
 
 * User with C compiler
1132
 
 * Developers
1133
 
 
1134
 
The recommended way to install bzr is to have a C compiler so that the
1135
 
extensions can be built, but if no C compiler is present, the pure python
1136
 
versions we supply will work, though more slowly.
1137
 
 
1138
 
For developers we recommend that pyrex be installed, so that the C
1139
 
extensions can be changed if needed.
1140
 
 
1141
 
For the C extensions, the extension module should always match the
1142
 
original python one in all respects (modulo speed). This should be
1143
 
maintained over time.
1144
 
 
1145
 
To create an extension, add rules to setup.py for building it with pyrex,
1146
 
and with distutils. Now start with an empty .pyx file. At the top add
1147
 
"include 'yourmodule.py'". This will import the contents of foo.py into this 
1148
 
file at build time - remember that only one module will be loaded at
1149
 
runtime. Now you can subclass classes, or replace functions, and only your
1150
 
changes need to be present in the .pyx file.
1151
 
 
1152
 
Note that pyrex does not support all 2.4 programming idioms, so some
1153
 
syntax changes may be required. I.e. 
1154
 
 
1155
 
 - 'from foo import (bar, gam)' needs to change to not use the brackets. 
1156
 
 - 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar' 
1157
 
 
1158
 
If the changes are too dramatic, consider
1159
 
maintaining the python code twice - once in the .pyx, and once in the .py,
1160
 
and no longer including the .py file.
1161
 
 
1162
 
 
1163
 
Making Installers for OS Windows
1164
 
================================
1165
 
To build a win32 installer, see the instructions on the wiki page:
1166
 
http://bazaar-vcs.org/BzrWin32Installer
1167
 
 
1168
 
 
1169
 
..
1170
 
   vim: ft=rst tw=74 ai