« back to all changes in this revision
Viewing changes to doc/developers/HACKING
- browse files at revision 2363.5.10
- compare with another revision
- compare with revision 1185.11.1
- download diff
- download tarball
- view history from revision 2363.5.10
- Committer: Aaron Bentley
- Date: 2007-05-14 17:21:02 UTC
- mfrom: (2485 +trunk)
- mto: This revision was merged to the branch mainline in revision 2528.
- Revision ID: aaron.bentley@utoronto.ca-20070514172102-byyl4ldjxhfxvryy
Merge bzr.dev
- files added:
- doc/developers
- files renamed:
- HACKING => doc/developers/HACKING
- files modified:
- .bzrignore
added
removed
doc/developers/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::
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:
12
225
13
226
* New functionality should have test cases. Preferably write the
14
227
test before writing the code.
16
229
In general, you can test at either the command-line level or the
17
230
internal API level. See Writing Tests below for more detail.
18
231
19
* Try to practice Test-Driven Development. before fixing a bug, write a
232
* Try to practice Test-Driven Development: before fixing a bug, write a
20
233
test case so that it does not regress. Similarly for adding a new
21
234
feature: write a test case for a small version of the new feature before
22
235
starting on the code itself. Check the test fails on the old code, then
23
236
add the feature or fix and check it passes.
24
237
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
-------------------
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
376
Essential Domain Classes
377
########################
378
379
Introducing the Object Model
380
============================
381
382
The core domain objects within the bazaar model are:
383
384
* Transport
385
386
* Branch
387
388
* Repository
389
390
* WorkingTree
391
392
Transports are explained below. See http://bazaar-vcs.org/Classes/
393
for an introduction to the other key classes.
394
395
Using Transports
396
================
397
398
The ``Transport`` layer handles access to local or remote directories.
399
Each Transport object acts like a logical connection to a particular
400
directory, and it allows various operations on files within it. You can
401
*clone* a transport to get a new Transport connected to a subdirectory or
402
parent directory.
403
404
Transports are not used for access to the working tree. At present
405
working trees are always local and they are accessed through the regular
406
Python file io mechanisms.
407
408
Filenames vs URLs
409
-----------------
410
411
Transports work in URLs. Take note that URLs are by definition only
412
ASCII - the decision of how to encode a Unicode string into a URL must be
413
taken at a higher level, typically in the Store. (Note that Stores also
414
escape filenames which cannot be safely stored on all filesystems, but
415
this is a different level.)
416
417
The main reason for this is that it's not possible to safely roundtrip a
418
URL into Unicode and then back into the same URL. The URL standard
419
gives a way to represent non-ASCII bytes in ASCII (as %-escapes), but
420
doesn't say how those bytes represent non-ASCII characters. (They're not
421
guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
422
423
For example if the user enters the url ``http://example/%e0`` there's no
424
way to tell whether that character represents "latin small letter a with
425
grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2
426
or malformed UTF-8. So we can't convert their URL to Unicode reliably.
427
428
Equally problematic if we're given a url-like string containing non-ascii
429
characters (such as the accented a) we can't be sure how to convert that
430
to the correct URL, because we don't know what encoding the server expects
431
for those characters. (Although this is not totally reliable we might still
432
accept these and assume they should be put into UTF-8.)
433
434
A similar edge case is that the url ``http://foo/sweet%2Fsour`` contains
435
one directory component whose name is "sweet/sour". The escaped slash is
436
not a directory separator. If we try to convert URLs to regular Unicode
437
paths this information will be lost.
438
439
This implies that Transports must natively deal with URLs; for simplicity
440
they *only* deal with URLs and conversion of other strings to URLs is done
441
elsewhere. Information they return, such as from ``list_dir``, is also in
442
the form of URL components.
443
444
445
Core Topics
446
###########
447
448
Evolving Interfaces
449
===================
50
450
51
451
We have a commitment to 6 months API stability - any supported symbol in a
52
452
release of bzr MUST NOT be altered in any way that would result in
72
472
callers will at least get an AttributeError rather than weird results.
73
473
74
474
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
============
475
Coding Style Guidelines
476
=======================
197
477
198
478
Please write PEP-8__ compliant code.
199
479
203
483
__ http://www.python.org/peps/pep-0008.html
204
484
205
485
486
Module Imports
487
--------------
488
489
* Imports should be done at the top-level of the file, unless there is
490
a strong reason to have them lazily loaded when a particular
491
function runs. Import statements have a cost, so try to make sure
492
they don't run inside hot functions.
493
494
* Module names should always be given fully-qualified,
495
i.e. ``bzrlib.hashcache`` not just ``hashcache``.
496
206
497
207
498
Naming
208
499
------
224
515
inconsistency if other people use the full name.
225
516
226
517
227
Standard names
518
Standard Names
228
519
--------------
229
520
230
521
``revision_id`` not ``rev_id`` or ``revid``
331
622
object, rather than the real class.
332
623
333
624
334
Passing to other variables
625
Passing to Other Variables
335
626
~~~~~~~~~~~~~~~~~~~~~~~~~~
336
627
337
628
It also is incorrect to assign ``ImportReplacer`` objects to other variables.
342
633
variable, so some bugs are not detected right away.
343
634
344
635
345
Writing output
636
Getting Input
637
=============
638
639
Processing Command Lines
640
------------------------
641
642
bzrlib has a standard framework for parsing command lines and calling
643
processing routines associated with various commands. See builtins.py
644
for numerous examples.
645
646
647
Standard Parameter Types
648
------------------------
649
650
There are some common requirements in the library: some parameters need to be
651
unicode safe, some need byte strings, and so on. At the moment we have
652
only codified one specific pattern: Parameters that need to be unicode
653
should be checked via ``bzrlib.osutils.safe_unicode``. This will coerce the
654
input into unicode in a consistent fashion, allowing trivial strings to be
655
used for programmer convenience, but not performing unpredictably in the
656
presence of different locales.
657
658
659
Writing Output
346
660
==============
347
661
348
662
(The strategy described here is what we want to get to, but it's not
379
693
should be only in the command-line tool.
380
694
381
695
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
Running tests
438
=============
439
Currently, bzr selftest is used to invoke tests.
440
You can provide a pattern argument to run a subset. For example,
441
to run just the blackbox tests, run::
442
443
./bzr selftest -v blackbox
444
445
To skip a particular test (or set of tests), use the --exclude option
446
(shorthand -x) like so::
447
448
./bzr selftest -v -x blackbox
449
450
To list tests without running them, use the --list-only option like so::
451
452
./bzr selftest --list-only
453
454
This option can be combined with other selftest options (like -x) and
455
filter patterns to understand their effect.
456
457
458
Errors and exceptions
459
=====================
460
461
Errors are handled through Python exceptions.
696
Handling Errors and Exceptions
697
==============================
698
699
Commands should return non-zero when they encounter circumstances that
700
the user should really pay attention to - which includes trivial shell
701
pipelines.
702
703
Recommended values are:
704
705
0. OK.
706
1. Conflicts in merge-like operations, or changes are present in
707
diff-like operations.
708
2. Unrepresentable diff changes (i.e. binary files that we cannot show
709
a diff of).
710
3. An error or exception has occurred.
711
712
Errors are handled through Python exceptions. Exceptions should be defined
713
inside bzrlib.errors, so that we can see the whole tree at a glance.
462
714
463
715
We broadly classify errors as either being either internal or not,
464
depending on whether ``user_error`` is set or not. If we think it's our
716
depending on whether ``internal_error`` is set or not. If we think it's our
465
717
fault, we show a backtrace, an invitation to report the bug, and possibly
466
718
other details. This is the default for errors that aren't specifically
467
719
recognized as being caused by a user error. Otherwise we show a briefer
492
744
final fullstop. If long, they may contain newlines to break the text.
493
745
494
746
747
Documenting Changes
748
===================
749
750
When you change bzrlib, please update the relevant documentation for the
751
change you made: Changes to commands should update their help, and
752
possibly end user tutorials; changes to the core library should be
753
reflected in API documentation.
754
755
NEWS File
756
---------
757
758
If you make a user-visible change, please add a note to the NEWS file.
759
The description should be written to make sense to someone who's just
760
a user of bzr, not a developer: new functions or classes shouldn't be
761
mentioned, but new commands, changes in behaviour or fixed nontrivial
762
bugs should be listed. See the existing entries for an idea of what
763
should be done.
764
765
Within each release, entries in the news file should have the most
766
user-visible changes first. So the order should be approximately:
767
768
* changes to existing behaviour - the highest priority because the
769
user's existing knowledge is incorrect
770
* new features - should be brought to their attention
771
* bug fixes - may be of interest if the bug was affecting them, and
772
should include the bug number if any
773
* major documentation changes
774
* changes to internal interfaces
775
776
People who made significant contributions to each change are listed in
777
parenthesis. This can include reporting bugs (particularly with good
778
details or reproduction recipes), submitting patches, etc.
779
780
Commands
781
--------
782
783
The docstring of a command is used by ``bzr help`` to generate help output
784
for the command. The list 'takes_options' attribute on a command is used by
785
``bzr help`` to document the options for the command - the command
786
docstring does not need to document them. Finally, the '_see_also'
787
attribute on a command can be used to reference other related help topics.
788
789
API Documentation
790
-----------------
791
792
Functions, methods, classes and modules should have docstrings
793
describing how they are used.
794
795
The first line of the docstring should be a self-contained sentence.
796
797
For the special case of Command classes, this acts as the user-visible
798
documentation shown by the help command.
799
800
The docstrings should be formatted as reStructuredText_ (like this
801
document), suitable for processing using the epydoc_ tool into HTML
802
documentation.
803
804
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
805
.. _epydoc: http://epydoc.sourceforge.net/
806
807
808
General Guidelines
809
==================
810
811
Copyright
812
---------
813
814
The copyright policy for bzr was recently made clear in this email (edited
815
for grammatical correctness)::
816
817
The attached patch cleans up the copyright and license statements in
818
the bzr source. It also adds tests to help us remember to add them
819
with the correct text.
820
821
We had the problem that lots of our files were "Copyright Canonical
822
Development Ltd" which is not a real company, and some other variations
823
on this theme. Also, some files were missing the GPL statements.
824
825
I want to be clear about the intent of this patch, since copyright can
826
be a little controversial.
827
828
1) The big motivation for this is not to shut out the community, but
829
just to clean up all of the invalid copyright statements.
830
831
2) It has been the general policy for bzr that we want a single
832
copyright holder for all of the core code. This is following the model
833
set by the FSF, which makes it easier to update the code to a new
834
license in case problems are encountered. (For example, if we want to
835
upgrade the project universally to GPL v3 it is much simpler if there is
836
a single copyright holder). It also makes it clearer if copyright is
837
ever debated, there is a single holder, which makes it easier to defend
838
in court, etc. (I think the FSF position is that if you assign them
839
copyright, they can defend it in court rather than you needing to, and
840
I'm sure Canonical would do the same).
841
As such, Canonical has requested copyright assignments from all of the
842
major contributers.
843
844
3) If someone wants to add code and not attribute it to Canonical, there
845
is a specific list of files that are excluded from this check. And the
846
test failure indicates where that is, and how to update it.
847
848
4) If anyone feels that I changed a copyright statement incorrectly, just
849
let me know, and I'll be happy to correct it. Whenever you have large
850
mechanical changes like this, it is possible to make some mistakes.
851
852
Just to reiterate, this is a community project, and it is meant to stay
853
that way. Core bzr code is copyright Canonical for legal reasons, and
854
the tests are just there to help us maintain that.
855
856
857
Miscellaneous Topics
858
####################
495
859
496
860
Debugging
497
861
=========
505
869
then bzr will go into pdb post-mortem mode when an unhandled exception
506
870
occurs.
507
871
508
If you send a SIGQUIT signal to bzr, which can be done by pressing C-\ on Unix,
509
bzr will go into the debugger immediately. You can continue execution by
510
typing ``c``. This can be disabled if necessary by setting the
511
environment variable ``BZR_SIGQUIT_PDB=0``.
512
872
If you send a SIGQUIT signal to bzr, which can be done by pressing
873
Ctrl-\\ on Unix, bzr will go into the debugger immediately. You can
874
continue execution by typing ``c``. This can be disabled if necessary
875
by setting the environment variable ``BZR_SIGQUIT_PDB=0``.
513
876
514
877
515
878
Jargon
521
884
indexes into the branch's revision history.
522
885
523
886
524
Transport
525
=========
526
527
The ``Transport`` layer handles access to local or remote directories.
528
Each Transport object acts like a logical connection to a particular
529
directory, and it allows various operations on files within it. You can
530
*clone* a transport to get a new Transport connected to a subdirectory or
531
parent directory.
532
533
Transports are not used for access to the working tree. At present
534
working trees are always local and they are accessed through the regular
535
Python file io mechanisms.
536
537
filenames vs URLs
538
-----------------
539
540
Transports work in URLs. Take note that URLs are by definition only
541
ASCII - the decision of how to encode a Unicode string into a URL must be
542
taken at a higher level, typically in the Store. (Note that Stores also
543
escape filenames which cannot be safely stored on all filesystems, but
544
this is a different level.)
545
546
The main reason for this is that it's not possible to safely roundtrip a
547
URL into Unicode and then back into the same URL. The URL standard
548
gives a way to represent non-ASCII bytes in ASCII (as %-escapes), but
549
doesn't say how those bytes represent non-ASCII characters. (They're not
550
guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
551
552
For example if the user enters the url ``http://example/%e0`` there's no
553
way to tell whether that character represents "latin small letter a with
554
grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2
555
or malformed UTF-8. So we can't convert their URL to Unicode reliably.
556
557
Equally problematic if we're given a url-like string containing non-ascii
558
characters (such as the accented a) we can't be sure how to convert that
559
to the correct URL, because we don't know what encoding the server expects
560
for those characters. (Although this is not totally reliable we might still
561
accept these and assume they should be put into UTF-8.)
562
563
A similar edge case is that the url ``http://foo/sweet%2Fsour`` contains
564
one directory component whose name is "sweet/sour". The escaped slash is
565
not a directory separator. If we try to convert URLs to regular Unicode
566
paths this information will be lost.
567
568
This implies that Transports must natively deal with URLs; for simplicity
569
they *only* deal with URLs and conversion of other strings to URLs is done
570
elsewhere. Information they return, such as from ``list_dir``, is also in
571
the form of URL components.
572
573
574
887
Unicode and Encoding Support
575
888
============================
576
889
637
950
Use ``bzrlib.osutils.rmtree`` instead.
638
951
639
952
640
Merge/review process
641
====================
642
643
If you'd like to propose a change, please post to the
644
bazaar@lists.canonical.com list with a patch, bzr changeset, or link to a
645
branch. Please put '[patch]' in the subject so we can pick them out, and
646
include some text explaining the change. Remember to put an update to the NEWS
647
file in your diff, if it makes any changes visible to users or plugin
648
developers. Please include a diff against mainline if you're giving a link to
649
a branch.
650
651
Please indicate if you think the code is ready to merge, or if it's just a
652
draft or for discussion. If you want comments from many developers rather than
653
to be merged, you can put '[rfc]' in the subject lines.
654
655
Anyone is welcome to review code. There are broadly three gates for
656
code to get in:
657
658
* Doesn't reduce test coverage: if it adds new methods or commands,
659
there should be tests for them. There is a good test framework
660
and plenty of examples to crib from, but if you are having trouble
661
working out how to test something feel free to post a draft patch
662
and ask for help.
663
664
* Doesn't reduce design clarity, such as by entangling objects
665
we're trying to separate. This is mostly something the more
666
experienced reviewers need to help check.
667
668
* Improves bugs, features, speed, or code simplicity.
669
670
Code that goes in should pass all three.
671
672
If you read a patch please reply and say so. We can use a numeric scale
673
of -1, -0, +0, +1, meaning respectively "really don't want it in current
674
form", "somewhat uncomfortable", "ok with me", and "please put it in".
675
Anyone can "vote". (It's not really voting, just a terse expression.)
676
677
If something gets say two +1 votes from core reviewers, and no
678
vetos, then it's OK to come in. Any of the core developers can bring it
679
into their integration branch, which I'll merge regularly. (If you do
680
so, please reply and say so.)
681
682
683
953
C Extension Modules
684
954
===================
685
955
718
988
maintaining the python code twice - once in the .pyx, and once in the .py,
719
989
and no longer including the .py file.
720
990
721
Making installers for OS Windows
991
992
Making Installers for OS Windows
722
993
================================
723
994
To build a win32 installer, see the instructions on the wiki page:
724
995
http://bazaar-vcs.org/BzrWin32Installer
725
996
726
997
727
:: vim: ft=rst tw=74 ai
998
..
999
vim: ft=rst tw=74 ai
Loggerhead is a web-based interface for Breezy
Version: 2.0.1