« back to all changes in this revision
Viewing changes to HACKING
- browse files at revision 2475.2.3
- compare with another revision
- compare with revision 2594
- download diff
- download tarball
- view history from revision 2475.2.3
- Committer: Martin Pool
- Date: 2007-05-03 06:19:11 UTC
- mfrom: (2466.6.3 bzr.HACKING)
- mto: This revision was merged to the branch mainline in revision 2477.
- Revision ID: mbp@sourcefrog.net-20070503061911-1mmho1eh1pz7y950
Merge ian's HACKING updates
- files modified:
- HACKING
added
removed
HACKING
1
============================
2
Guidelines for modifying bzr
3
============================
1
======================
2
Bazaar Developer Guide
3
======================
4
4
5
5
.. contents::
6
6
7
7
(The current version of this document is available in the file ``HACKING``
8
in the source tree, or at http://doc.bazaar-vcs.org/current/hacking.html)
9
10
Overall
11
=======
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: bzr branch http://bazaar-vcs.org/bzr/bzr.dev/ bzr.dev
187
188
* keep your copy of bzr.dev prestine (by not developing in it) and keep
189
it up to date (by using bzr pull)
190
191
* create a new branch off your local bzr.dev copy for each issue
192
(bug or feature) you are working on.
193
194
This approach makes it easy to go back and make any required changes
195
after a code review. Resubmitting the change is then simple with no
196
risk of accidentially including edits related to other issues you may
197
be working on. After the changes for an issue are accepted and merged,
198
the associated branch can be deleted or archived as you wish.
199
200
201
Navigating the Code Base
202
========================
203
204
TODO: List and describe in one line the purpose of each directory
205
inside an installation of bzr.
206
207
TODO: Refer to a central location holding an up to date copy of the API
208
documentation generated by epydoc, e.g. something like
209
http://starship.python.net/crew/mwh/bzrlibapi/bzrlib.html.
210
211
212
Testing Bazaar
213
##############
214
215
The Importance of Testing
216
=========================
217
218
Reliability is a critical success factor for any Version Control System.
219
We want Bazaar to be highly reliable across multiple platforms while
220
evolving over time to meet the needs of its community.
221
222
In a nutshell, this is want we expect and encourage:
12
223
13
224
* New functionality should have test cases. Preferably write the
14
225
test before writing the code.
16
227
In general, you can test at either the command-line level or the
17
228
internal API level. See Writing Tests below for more detail.
18
229
19
* Try to practice Test-Driven Development. before fixing a bug, write a
230
* Try to practice Test-Driven Development: before fixing a bug, write a
20
231
test case so that it does not regress. Similarly for adding a new
21
232
feature: write a test case for a small version of the new feature before
22
233
starting on the code itself. Check the test fails on the old code, then
23
234
add the feature or fix and check it passes.
24
235
25
* Exceptions should be defined inside bzrlib.errors, so that we can
26
see the whole tree at a glance.
27
28
* Imports should be done at the top-level of the file, unless there is
29
a strong reason to have them lazily loaded when a particular
30
function runs. Import statements have a cost, so try to make sure
31
they don't run inside hot functions.
32
33
* Module names should always be given fully-qualified,
34
i.e. ``bzrlib.hashcache`` not just ``hashcache``.
35
36
* Commands should return non-zero when they encounter circumstances that
37
the user should really pay attention to - which includes trivial shell
38
pipelines.
39
40
Recommended values are
41
0. OK,
42
1. Conflicts in merge-like operations, or changes are present in
43
diff-like operations.
44
2. Unrepresentable diff changes (i.e. binary files that we cannot show
45
a diff of).
46
3. An error or exception has occurred.
47
48
Evolving interfaces
49
-------------------
236
By doing these things, the Bazaar team gets increased confidence that
237
changes do what they claim to do, whether provided by the core team or
238
by community members. Equally importantly, we can be surer that changes
239
down the track do not break new features or bug fixes that you are
240
contributing today.
241
242
As of May 2007, Bazaar ships with a test suite containing over 6000 tests
243
and growing. We are proud of it and want to remain so. As community
244
members, we all benefit from it. Would you trust version control on
245
your project to a product *without* a test suite like Bazaar has?
246
247
248
Running the Test Suite
249
======================
250
251
Currently, bzr selftest is used to invoke tests.
252
You can provide a pattern argument to run a subset. For example,
253
to run just the blackbox tests, run::
254
255
./bzr selftest -v blackbox
256
257
To skip a particular test (or set of tests), use the --exclude option
258
(shorthand -x) like so::
259
260
./bzr selftest -v -x blackbox
261
262
To list tests without running them, use the --list-only option like so::
263
264
./bzr selftest --list-only
265
266
This option can be combined with other selftest options (like -x) and
267
filter patterns to understand their effect.
268
269
270
Writing Tests
271
=============
272
273
In general tests should be placed in a file named test_FOO.py where
274
FOO is the logical thing under test. That file should be placed in the
275
tests subdirectory under the package being tested.
276
277
For example, tests for merge3 in bzrlib belong in bzrlib/tests/test_merge3.py.
278
See bzrlib/tests/test_sampler.py for a template test script.
279
280
Tests can be written for the UI or for individual areas of the library.
281
Choose whichever is appropriate: if adding a new command, or a new command
282
option, then you should be writing a UI test. If you are both adding UI
283
functionality and library functionality, you will want to write tests for
284
both the UI and the core behaviours. We call UI tests 'blackbox' tests
285
and they are found in ``bzrlib/tests/blackbox/*.py``.
286
287
When writing blackbox tests please honour the following conventions:
288
289
1. Place the tests for the command 'name' in
290
bzrlib/tests/blackbox/test_name.py. This makes it easy for developers
291
to locate the test script for a faulty command.
292
293
2. Use the 'self.run_bzr("name")' utility function to invoke the command
294
rather than running bzr in a subprocess or invoking the
295
cmd_object.run() method directly. This is a lot faster than
296
subprocesses and generates the same logging output as running it in a
297
subprocess (which invoking the method directly does not).
298
299
3. Only test the one command in a single test script. Use the bzrlib
300
library when setting up tests and when evaluating the side-effects of
301
the command. We do this so that the library api has continual pressure
302
on it to be as functional as the command line in a simple manner, and
303
to isolate knock-on effects throughout the blackbox test suite when a
304
command changes its name or signature. Ideally only the tests for a
305
given command are affected when a given command is changed.
306
307
4. If you have a test which does actually require running bzr in a
308
subprocess you can use ``run_bzr_subprocess``. By default the spawned
309
process will not load plugins unless ``--allow-plugins`` is supplied.
310
311
312
Doctests
313
--------
314
315
We make selective use of doctests__. In general they should provide
316
*examples* within the API documentation which can incidentally be tested. We
317
don't try to test every important case using doctests -- regular Python
318
tests are generally a better solution.
319
320
Most of these are in ``bzrlib/doc/api``. More additions are welcome.
321
322
__ http://docs.python.org/lib/module-doctest.html
323
324
325
Skipping tests and test requirements
326
------------------------------------
327
328
In our enhancements to unittest we allow for some addition results beyond
329
just success or failure.
330
331
If a test can't be run, it can say that it's skipped. This is typically
332
used in parameterized tests - for example if a transport doesn't support
333
setting permissions, we'll skip the tests that relating to that. ::
334
335
try:
336
return self.branch_format.initialize(repo.bzrdir)
337
except errors.UninitializableFormat:
338
raise tests.TestSkipped('Uninitializable branch format')
339
340
Raising TestSkipped is a good idea when you want to make it clear that the
341
test was not run, rather than just returning which makes it look as if it
342
was run and passed.
343
344
A subtly different case is a test that should run, but can't run in the
345
current environment. This covers tests that can only run in particular
346
operating systems or locales, or that depend on external libraries. Here
347
we want to inform the user that they didn't get full test coverage, but
348
they possibly could if they installed more libraries. These are expressed
349
as a dependency on a feature so we can summarise them, and so that the
350
test for the feature is done only once. (For historical reasons, as of
351
May 2007 many cases that should depend on features currently raise
352
TestSkipped.) The typical use is::
353
354
class TestStrace(TestCaseWithTransport):
355
356
_test_needs_features = [StraceFeature]
357
358
which means all tests in this class need the feature. The feature itself
359
should provide a ``_probe`` method which is called once to determine if
360
it's available.
361
362
363
Known failures
364
--------------
365
366
Known failures are when a test exists but we know it currently doesn't
367
work, allowing the test suite to still pass. These should be used with
368
care, we don't want a proliferation of quietly broken tests. It might be
369
appropriate to use them if you've committed a test for a bug but not the
370
fix for it, or if something works on Unix but not on Windows.
371
372
373
374
Essential Domain Classes
375
########################
376
377
Introducing the Object Model
378
============================
379
380
The core domain objects within the bazaar model are:
381
382
* Transport
383
384
* Branch
385
386
* Repository
387
388
* WorkingTree
389
390
Transports are explained below. See http://bazaar-vcs.org/Classes/
391
for an introduction to the other key classes.
392
393
Using Transports
394
================
395
396
The ``Transport`` layer handles access to local or remote directories.
397
Each Transport object acts like a logical connection to a particular
398
directory, and it allows various operations on files within it. You can
399
*clone* a transport to get a new Transport connected to a subdirectory or
400
parent directory.
401
402
Transports are not used for access to the working tree. At present
403
working trees are always local and they are accessed through the regular
404
Python file io mechanisms.
405
406
Filenames vs URLs
407
-----------------
408
409
Transports work in URLs. Take note that URLs are by definition only
410
ASCII - the decision of how to encode a Unicode string into a URL must be
411
taken at a higher level, typically in the Store. (Note that Stores also
412
escape filenames which cannot be safely stored on all filesystems, but
413
this is a different level.)
414
415
The main reason for this is that it's not possible to safely roundtrip a
416
URL into Unicode and then back into the same URL. The URL standard
417
gives a way to represent non-ASCII bytes in ASCII (as %-escapes), but
418
doesn't say how those bytes represent non-ASCII characters. (They're not
419
guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
420
421
For example if the user enters the url ``http://example/%e0`` there's no
422
way to tell whether that character represents "latin small letter a with
423
grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2
424
or malformed UTF-8. So we can't convert their URL to Unicode reliably.
425
426
Equally problematic if we're given a url-like string containing non-ascii
427
characters (such as the accented a) we can't be sure how to convert that
428
to the correct URL, because we don't know what encoding the server expects
429
for those characters. (Although this is not totally reliable we might still
430
accept these and assume they should be put into UTF-8.)
431
432
A similar edge case is that the url ``http://foo/sweet%2Fsour`` contains
433
one directory component whose name is "sweet/sour". The escaped slash is
434
not a directory separator. If we try to convert URLs to regular Unicode
435
paths this information will be lost.
436
437
This implies that Transports must natively deal with URLs; for simplicity
438
they *only* deal with URLs and conversion of other strings to URLs is done
439
elsewhere. Information they return, such as from ``list_dir``, is also in
440
the form of URL components.
441
442
443
Core Topics
444
###########
445
446
Evolving Interfaces
447
===================
50
448
51
449
We have a commitment to 6 months API stability - any supported symbol in a
52
450
release of bzr MUST NOT be altered in any way that would result in
72
470
callers will at least get an AttributeError rather than weird results.
73
471
74
472
75
Standard parameter types
76
------------------------
77
78
There are some common requirements in the library: some parameters need to be
79
unicode safe, some need byte strings, and so on. At the moment we have
80
only codified one specific pattern: Parameters that need to be unicode
81
should be checked via ``bzrlib.osutils.safe_unicode``. This will coerce the
82
input into unicode in a consistent fashion, allowing trivial strings to be
83
used for programmer convenience, but not performing unpredictably in the
84
presence of different locales.
85
86
87
Copyright
88
---------
89
90
The copyright policy for bzr was recently made clear in this email (edited
91
for grammatical correctness)::
92
93
The attached patch cleans up the copyright and license statements in
94
the bzr source. It also adds tests to help us remember to add them
95
with the correct text.
96
97
We had the problem that lots of our files were "Copyright Canonical
98
Development Ltd" which is not a real company, and some other variations
99
on this theme. Also, some files were missing the GPL statements.
100
101
I want to be clear about the intent of this patch, since copyright can
102
be a little controversial.
103
104
1) The big motivation for this is not to shut out the community, but
105
just to clean up all of the invalid copyright statements.
106
107
2) It has been the general policy for bzr that we want a single
108
copyright holder for all of the core code. This is following the model
109
set by the FSF, which makes it easier to update the code to a new
110
license in case problems are encountered. (For example, if we want to
111
upgrade the project universally to GPL v3 it is much simpler if there is
112
a single copyright holder). It also makes it clearer if copyright is
113
ever debated, there is a single holder, which makes it easier to defend
114
in court, etc. (I think the FSF position is that if you assign them
115
copyright, they can defend it in court rather than you needing to, and
116
I'm sure Canonical would do the same).
117
As such, Canonical has requested copyright assignments from all of the
118
major contributers.
119
120
3) If someone wants to add code and not attribute it to Canonical, there
121
is a specific list of files that are excluded from this check. And the
122
test failure indicates where that is, and how to update it.
123
124
4) If anyone feels that I changed a copyright statement incorrectly, just
125
let me know, and I'll be happy to correct it. Whenever you have large
126
mechanical changes like this, it is possible to make some mistakes.
127
128
Just to reiterate, this is a community project, and it is meant to stay
129
that way. Core bzr code is copyright Canonical for legal reasons, and
130
the tests are just there to help us maintain that.
131
132
133
Documentation
134
=============
135
136
When you change bzrlib, please update the relevant documentation for the
137
change you made: Changes to commands should update their help, and
138
possibly end user tutorials; changes to the core library should be
139
reflected in API documentation.
140
141
Commands
142
--------
143
144
The docstring of a command is used by ``bzr help`` to generate help output
145
for the command. The list 'takes_options' attribute on a command is used by
146
``bzr help`` to document the options for the command - the command
147
docstring does not need to document them. Finally, the '_see_also'
148
attribute on a command can be used to reference other related help topics.
149
150
NEWS file
151
---------
152
153
If you make a user-visible change, please add a note to the NEWS file.
154
The description should be written to make sense to someone who's just
155
a user of bzr, not a developer: new functions or classes shouldn't be
156
mentioned, but new commands, changes in behaviour or fixed nontrivial
157
bugs should be listed. See the existing entries for an idea of what
158
should be done.
159
160
Within each release, entries in the news file should have the most
161
user-visible changes first. So the order should be approximately:
162
163
* changes to existing behaviour - the highest priority because the
164
user's existing knowledge is incorrect
165
* new features - should be brought to their attention
166
* bug fixes - may be of interest if the bug was affecting them, and
167
should include the bug number if any
168
* major documentation changes
169
* changes to internal interfaces
170
171
People who made significant contributions to each change are listed in
172
parenthesis. This can include reporting bugs (particularly with good
173
details or reproduction recipes), submitting patches, etc.
174
175
API documentation
176
-----------------
177
178
Functions, methods, classes and modules should have docstrings
179
describing how they are used.
180
181
The first line of the docstring should be a self-contained sentence.
182
183
For the special case of Command classes, this acts as the user-visible
184
documentation shown by the help command.
185
186
The docstrings should be formatted as reStructuredText_ (like this
187
document), suitable for processing using the epydoc_ tool into HTML
188
documentation.
189
190
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
191
.. _epydoc: http://epydoc.sourceforge.net/
192
193
194
195
Coding style
196
============
473
Coding Style Guidelines
474
=======================
197
475
198
476
Please write PEP-8__ compliant code.
199
477
203
481
__ http://www.python.org/peps/pep-0008.html
204
482
205
483
484
Module Imports
485
--------------
486
487
* Imports should be done at the top-level of the file, unless there is
488
a strong reason to have them lazily loaded when a particular
489
function runs. Import statements have a cost, so try to make sure
490
they don't run inside hot functions.
491
492
* Module names should always be given fully-qualified,
493
i.e. ``bzrlib.hashcache`` not just ``hashcache``.
494
206
495
207
496
Naming
208
497
------
224
513
inconsistency if other people use the full name.
225
514
226
515
227
Standard names
516
Standard Names
228
517
--------------
229
518
230
519
``revision_id`` not ``rev_id`` or ``revid``
331
620
object, rather than the real class.
332
621
333
622
334
Passing to other variables
623
Passing to Other Variables
335
624
~~~~~~~~~~~~~~~~~~~~~~~~~~
336
625
337
626
It also is incorrect to assign ``ImportReplacer`` objects to other variables.
342
631
variable, so some bugs are not detected right away.
343
632
344
633
345
Writing output
634
Getting Input
635
=============
636
637
Processing Command Lines
638
------------------------
639
640
bzrlib has a standard framework for parsing command lines and calling
641
processing routines associated with various commands. See builtins.py
642
for numerous examples.
643
644
645
Standard Parameter Types
646
------------------------
647
648
There are some common requirements in the library: some parameters need to be
649
unicode safe, some need byte strings, and so on. At the moment we have
650
only codified one specific pattern: Parameters that need to be unicode
651
should be checked via ``bzrlib.osutils.safe_unicode``. This will coerce the
652
input into unicode in a consistent fashion, allowing trivial strings to be
653
used for programmer convenience, but not performing unpredictably in the
654
presence of different locales.
655
656
657
Writing Output
346
658
==============
347
659
348
660
(The strategy described here is what we want to get to, but it's not
379
691
should be only in the command-line tool.
380
692
381
693
382
Writing tests
383
=============
384
385
In general tests should be placed in a file named test_FOO.py where
386
FOO is the logical thing under test. That file should be placed in the
387
tests subdirectory under the package being tested.
388
389
For example, tests for merge3 in bzrlib belong in bzrlib/tests/test_merge3.py.
390
See bzrlib/tests/test_sampler.py for a template test script.
391
392
Tests can be written for the UI or for individual areas of the library.
393
Choose whichever is appropriate: if adding a new command, or a new command
394
option, then you should be writing a UI test. If you are both adding UI
395
functionality and library functionality, you will want to write tests for
396
both the UI and the core behaviours. We call UI tests 'blackbox' tests
397
and they are found in ``bzrlib/tests/blackbox/*.py``.
398
399
When writing blackbox tests please honour the following conventions:
400
401
1. Place the tests for the command 'name' in
402
bzrlib/tests/blackbox/test_name.py. This makes it easy for developers
403
to locate the test script for a faulty command.
404
405
2. Use the 'self.run_bzr("name")' utility function to invoke the command
406
rather than running bzr in a subprocess or invoking the
407
cmd_object.run() method directly. This is a lot faster than
408
subprocesses and generates the same logging output as running it in a
409
subprocess (which invoking the method directly does not).
410
411
3. Only test the one command in a single test script. Use the bzrlib
412
library when setting up tests and when evaluating the side-effects of
413
the command. We do this so that the library api has continual pressure
414
on it to be as functional as the command line in a simple manner, and
415
to isolate knock-on effects throughout the blackbox test suite when a
416
command changes its name or signature. Ideally only the tests for a
417
given command are affected when a given command is changed.
418
419
4. If you have a test which does actually require running bzr in a
420
subprocess you can use ``run_bzr_subprocess``. By default the spawned
421
process will not load plugins unless ``--allow-plugins`` is supplied.
422
423
424
Doctests
425
--------
426
427
We make selective use of doctests__. In general they should provide
428
*examples* within the API documentation which can incidentally be tested. We
429
don't try to test every important case using doctests -- regular Python
430
tests are generally a better solution.
431
432
Most of these are in ``bzrlib/doc/api``. More additions are welcome.
433
434
__ http://docs.python.org/lib/module-doctest.html
435
436
437
438
Skipping tests and test requirements
439
------------------------------------
440
441
In our enhancements to unittest we allow for some addition results beyond
442
just success or failure.
443
444
If a test can't be run, it can say that it's skipped. This is typically
445
used in parameterized tests - for example if a transport doesn't support
446
setting permissions, we'll skip the tests that relating to that. ::
447
448
try:
449
return self.branch_format.initialize(repo.bzrdir)
450
except errors.UninitializableFormat:
451
raise tests.TestSkipped('Uninitializable branch format')
452
453
Raising TestSkipped is a good idea when you want to make it clear that the
454
test was not run, rather than just returning which makes it look as if it
455
was run and passed.
456
457
A subtly different case is a test that should run, but can't run in the
458
current environment. This covers tests that can only run in particular
459
operating systems or locales, or that depend on external libraries. Here
460
we want to inform the user that they didn't get full test coverage, but
461
they possibly could if they installed more libraries. These are expressed
462
as a dependency on a feature so we can summarise them, and so that the
463
test for the feature is done only once. (For historical reasons, as of
464
May 2007 many cases that should depend on features currently raise
465
TestSkipped.) The typical use is::
466
467
class TestStrace(TestCaseWithTransport):
468
469
_test_needs_features = [StraceFeature]
470
471
which means all tests in this class need the feature. The feature itself
472
should provide a ``_probe`` method which is called once to determine if
473
it's available.
474
475
Known failures are when a test exists but we know it currently doesn't
476
work, allowing the test suite to still pass. These should be used with
477
care, we don't want a proliferation of quietly broken tests. It might be
478
appropriate to use them if you've committed a test for a bug but not the
479
fix for it, or if something works on Unix but not on Windows.
480
481
482
Running tests
483
=============
484
Currently, bzr selftest is used to invoke tests.
485
You can provide a pattern argument to run a subset. For example,
486
to run just the blackbox tests, run::
487
488
./bzr selftest -v blackbox
489
490
To skip a particular test (or set of tests), use the --exclude option
491
(shorthand -x) like so::
492
493
./bzr selftest -v -x blackbox
494
495
To list tests without running them, use the --list-only option like so::
496
497
./bzr selftest --list-only
498
499
This option can be combined with other selftest options (like -x) and
500
filter patterns to understand their effect.
501
502
503
Errors and exceptions
504
=====================
505
506
Errors are handled through Python exceptions.
694
Handling Errors and Exceptions
695
==============================
696
697
Commands should return non-zero when they encounter circumstances that
698
the user should really pay attention to - which includes trivial shell
699
pipelines.
700
701
Recommended values are:
702
703
0. OK.
704
1. Conflicts in merge-like operations, or changes are present in
705
diff-like operations.
706
2. Unrepresentable diff changes (i.e. binary files that we cannot show
707
a diff of).
708
3. An error or exception has occurred.
709
710
Errors are handled through Python exceptions. Exceptions should be defined
711
inside bzrlib.errors, so that we can see the whole tree at a glance.
507
712
508
713
We broadly classify errors as either being either internal or not,
509
714
depending on whether ``user_error`` is set or not. If we think it's our
537
742
final fullstop. If long, they may contain newlines to break the text.
538
743
539
744
745
Documenting Changes
746
===================
747
748
When you change bzrlib, please update the relevant documentation for the
749
change you made: Changes to commands should update their help, and
750
possibly end user tutorials; changes to the core library should be
751
reflected in API documentation.
752
753
NEWS File
754
---------
755
756
If you make a user-visible change, please add a note to the NEWS file.
757
The description should be written to make sense to someone who's just
758
a user of bzr, not a developer: new functions or classes shouldn't be
759
mentioned, but new commands, changes in behaviour or fixed nontrivial
760
bugs should be listed. See the existing entries for an idea of what
761
should be done.
762
763
Within each release, entries in the news file should have the most
764
user-visible changes first. So the order should be approximately:
765
766
* changes to existing behaviour - the highest priority because the
767
user's existing knowledge is incorrect
768
* new features - should be brought to their attention
769
* bug fixes - may be of interest if the bug was affecting them, and
770
should include the bug number if any
771
* major documentation changes
772
* changes to internal interfaces
773
774
People who made significant contributions to each change are listed in
775
parenthesis. This can include reporting bugs (particularly with good
776
details or reproduction recipes), submitting patches, etc.
777
778
Commands
779
--------
780
781
The docstring of a command is used by ``bzr help`` to generate help output
782
for the command. The list 'takes_options' attribute on a command is used by
783
``bzr help`` to document the options for the command - the command
784
docstring does not need to document them. Finally, the '_see_also'
785
attribute on a command can be used to reference other related help topics.
786
787
API Documentation
788
-----------------
789
790
Functions, methods, classes and modules should have docstrings
791
describing how they are used.
792
793
The first line of the docstring should be a self-contained sentence.
794
795
For the special case of Command classes, this acts as the user-visible
796
documentation shown by the help command.
797
798
The docstrings should be formatted as reStructuredText_ (like this
799
document), suitable for processing using the epydoc_ tool into HTML
800
documentation.
801
802
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
803
.. _epydoc: http://epydoc.sourceforge.net/
804
805
806
General Guidelines
807
==================
808
809
Copyright
810
---------
811
812
The copyright policy for bzr was recently made clear in this email (edited
813
for grammatical correctness)::
814
815
The attached patch cleans up the copyright and license statements in
816
the bzr source. It also adds tests to help us remember to add them
817
with the correct text.
818
819
We had the problem that lots of our files were "Copyright Canonical
820
Development Ltd" which is not a real company, and some other variations
821
on this theme. Also, some files were missing the GPL statements.
822
823
I want to be clear about the intent of this patch, since copyright can
824
be a little controversial.
825
826
1) The big motivation for this is not to shut out the community, but
827
just to clean up all of the invalid copyright statements.
828
829
2) It has been the general policy for bzr that we want a single
830
copyright holder for all of the core code. This is following the model
831
set by the FSF, which makes it easier to update the code to a new
832
license in case problems are encountered. (For example, if we want to
833
upgrade the project universally to GPL v3 it is much simpler if there is
834
a single copyright holder). It also makes it clearer if copyright is
835
ever debated, there is a single holder, which makes it easier to defend
836
in court, etc. (I think the FSF position is that if you assign them
837
copyright, they can defend it in court rather than you needing to, and
838
I'm sure Canonical would do the same).
839
As such, Canonical has requested copyright assignments from all of the
840
major contributers.
841
842
3) If someone wants to add code and not attribute it to Canonical, there
843
is a specific list of files that are excluded from this check. And the
844
test failure indicates where that is, and how to update it.
845
846
4) If anyone feels that I changed a copyright statement incorrectly, just
847
let me know, and I'll be happy to correct it. Whenever you have large
848
mechanical changes like this, it is possible to make some mistakes.
849
850
Just to reiterate, this is a community project, and it is meant to stay
851
that way. Core bzr code is copyright Canonical for legal reasons, and
852
the tests are just there to help us maintain that.
853
854
855
Miscellaneous Topics
856
####################
540
857
541
858
Debugging
542
859
=========
550
867
then bzr will go into pdb post-mortem mode when an unhandled exception
551
868
occurs.
552
869
553
If you send a SIGQUIT signal to bzr, which can be done by pressing C-\ on Unix,
554
bzr will go into the debugger immediately. You can continue execution by
555
typing ``c``. This can be disabled if necessary by setting the
556
environment variable ``BZR_SIGQUIT_PDB=0``.
557
870
If you send a SIGQUIT signal to bzr, which can be done by pressing
871
Ctrl-\\ on Unix, bzr will go into the debugger immediately. You can
872
continue execution by typing ``c``. This can be disabled if necessary
873
by setting the environment variable ``BZR_SIGQUIT_PDB=0``.
558
874
559
875
560
876
Jargon
566
882
indexes into the branch's revision history.
567
883
568
884
569
Transport
570
=========
571
572
The ``Transport`` layer handles access to local or remote directories.
573
Each Transport object acts like a logical connection to a particular
574
directory, and it allows various operations on files within it. You can
575
*clone* a transport to get a new Transport connected to a subdirectory or
576
parent directory.
577
578
Transports are not used for access to the working tree. At present
579
working trees are always local and they are accessed through the regular
580
Python file io mechanisms.
581
582
filenames vs URLs
583
-----------------
584
585
Transports work in URLs. Take note that URLs are by definition only
586
ASCII - the decision of how to encode a Unicode string into a URL must be
587
taken at a higher level, typically in the Store. (Note that Stores also
588
escape filenames which cannot be safely stored on all filesystems, but
589
this is a different level.)
590
591
The main reason for this is that it's not possible to safely roundtrip a
592
URL into Unicode and then back into the same URL. The URL standard
593
gives a way to represent non-ASCII bytes in ASCII (as %-escapes), but
594
doesn't say how those bytes represent non-ASCII characters. (They're not
595
guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
596
597
For example if the user enters the url ``http://example/%e0`` there's no
598
way to tell whether that character represents "latin small letter a with
599
grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2
600
or malformed UTF-8. So we can't convert their URL to Unicode reliably.
601
602
Equally problematic if we're given a url-like string containing non-ascii
603
characters (such as the accented a) we can't be sure how to convert that
604
to the correct URL, because we don't know what encoding the server expects
605
for those characters. (Although this is not totally reliable we might still
606
accept these and assume they should be put into UTF-8.)
607
608
A similar edge case is that the url ``http://foo/sweet%2Fsour`` contains
609
one directory component whose name is "sweet/sour". The escaped slash is
610
not a directory separator. If we try to convert URLs to regular Unicode
611
paths this information will be lost.
612
613
This implies that Transports must natively deal with URLs; for simplicity
614
they *only* deal with URLs and conversion of other strings to URLs is done
615
elsewhere. Information they return, such as from ``list_dir``, is also in
616
the form of URL components.
617
618
619
885
Unicode and Encoding Support
620
886
============================
621
887
682
948
Use ``bzrlib.osutils.rmtree`` instead.
683
949
684
950
685
Merge/review process
686
====================
687
688
If you'd like to propose a change, please post to the
689
bazaar@lists.canonical.com list with a patch, bzr changeset, or link to a
690
branch. Please put '[patch]' in the subject so we can pick them out, and
691
include some text explaining the change. Remember to put an update to the NEWS
692
file in your diff, if it makes any changes visible to users or plugin
693
developers. Please include a diff against mainline if you're giving a link to
694
a branch.
695
696
Please indicate if you think the code is ready to merge, or if it's just a
697
draft or for discussion. If you want comments from many developers rather than
698
to be merged, you can put '[rfc]' in the subject lines.
699
700
Anyone is welcome to review code. There are broadly three gates for
701
code to get in:
702
703
* Doesn't reduce test coverage: if it adds new methods or commands,
704
there should be tests for them. There is a good test framework
705
and plenty of examples to crib from, but if you are having trouble
706
working out how to test something feel free to post a draft patch
707
and ask for help.
708
709
* Doesn't reduce design clarity, such as by entangling objects
710
we're trying to separate. This is mostly something the more
711
experienced reviewers need to help check.
712
713
* Improves bugs, features, speed, or code simplicity.
714
715
Code that goes in should pass all three.
716
717
If you read a patch please reply and say so. We can use a numeric scale
718
of -1, -0, +0, +1, meaning respectively "really don't want it in current
719
form", "somewhat uncomfortable", "ok with me", and "please put it in".
720
Anyone can "vote". (It's not really voting, just a terse expression.)
721
722
If something gets say two +1 votes from core reviewers, and no
723
vetos, then it's OK to come in. Any of the core developers can bring it
724
into their integration branch, which I'll merge regularly. (If you do
725
so, please reply and say so.)
726
727
728
951
C Extension Modules
729
952
===================
730
953
763
986
maintaining the python code twice - once in the .pyx, and once in the .py,
764
987
and no longer including the .py file.
765
988
766
Making installers for OS Windows
989
990
Making Installers for OS Windows
767
991
================================
768
992
To build a win32 installer, see the instructions on the wiki page:
769
993
http://bazaar-vcs.org/BzrWin32Installer
Loggerhead is a web-based interface for Breezy
Version: 2.0.1