← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/HACKING.txt

  • Committer: Martin Pool
  • Date: 2010-01-31 15:28:41 UTC
  • mto: (4999.3.1 apport)
  • mto: This revision was merged to the branch mainline in revision 5002.
  • Revision ID: mbp@sourcefrog.net-20100131152841-uak92h8motai6xqo
Don't write crash reports if apport is configured to ignore them

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/HACKING.txt
2
2
Bazaar Developer Guide
3
3
======================
4
4
 
5
 
This document describes the Bazaar internals and the development process.
 
5
This document describes the Bazaar internals and the development process.  
6
6
It's meant for people interested in developing Bazaar, and some parts will
7
7
also be useful to people developing Bazaar plugins.
8
8
 
62
62
to involving the community before you spend much time on a change.
63
63
These include:
64
64
 
65
 
* you get to build on the wisdom of others, saving time
 
65
* you get to build on the wisdom on others, saving time
66
66
 
67
 
* if others can direct you to similar code, it minimises the work to be done
 
67
* if others can direct you to similar code, it minimises the work to be done 
68
68
 
69
69
* it assists everyone in coordinating direction, priorities and effort.
70
70
 
87
87
-----------------
88
88
 
89
89
First, get a local copy of the development mainline (See `Why make a local
90
 
copy of bzr.dev?`_.)
 
90
copy of bzr.dev?`_.) 
91
91
::
92
92
 
93
93
 $ bzr init-repo ~/bzr
100
100
 
101
101
This will give you a branch called "123456-my-bugfix" that you can work on
102
102
and commit in. Here, you can study the code, make a fix or a new feature.
103
 
Feel free to commit early and often (after all, it's your branch!).
 
103
Feel free to commit early and often (after all, it's your branch!). 
104
104
 
105
105
Documentation improvements are an easy place to get started giving back to the
106
106
Bazaar project.  The documentation is in the `doc/` subdirectory of the Bazaar
120
120
`your_lp_username`.  You can push your branch to Launchpad directly from
121
121
Bazaar::
122
122
 
123
 
  $ bzr push lp:~your_lp_username/bzr/meaningful_name_here
 
123
  $ bzr push lp:~your_lp_username/bzr/giveback
124
124
 
125
125
After you have pushed your branch, you will need to propose it for merging to
126
 
the Bazaar trunk.  Go to
127
 
<https://launchpad.net/your_lp_username/bzr/meaningful_name_here> and choose
128
 
"Propose for merging into another branch".  Select "~bzr/bzr/trunk" to hand
129
 
your changes off to the Bazaar developers for review and merging.
130
 
 
131
 
Using a meaningful name for your branch will help you and the reviewer(s)
132
 
better track the submission. Use a very succint description of your submission
133
 
and prefix it with bug number if needed (lp:~mbp/bzr/484558-merge-directory
134
 
for example). Alternatively, you can suffix with the bug number
135
 
(lp:~jameinel/bzr/export-file-511987).
136
 
 
 
126
the Bazaar trunk.  Go to <https://launchpad.net/your_lp_username/bzr/giveback>
 
127
and choose "Propose for merging into another branch".  Select "~bzr/bzr/trunk"
 
128
to hand your changes off to the Bazaar developers for review and merging.
137
129
 
138
130
Why make a local copy of bzr.dev?
139
131
---------------------------------
141
133
Making a local mirror of bzr.dev is not strictly necessary, but it means
142
134
 
143
135
- You can use that copy of bzr.dev as your main bzr executable, and keep it
144
 
  up-to-date using ``bzr pull``.
 
136
  up-to-date using ``bzr pull``.  
145
137
- Certain operations are faster, and can be done when offline.  For example:
146
138
 
147
139
  - ``bzr bundle``
148
140
  - ``bzr diff -r ancestor:...``
149
141
  - ``bzr merge``
150
142
 
151
 
- When it's time to create your next branch, it's more convenient.  When you
 
143
- When it's time to create your next branch, it's more convenient.  When you 
152
144
  have further contributions to make, you should do them in their own branch::
153
145
 
154
146
    $ cd ~/bzr
201
193
 
202
194
* create a local copy of the main development branch (bzr.dev) by using
203
195
  this command::
204
 
 
 
196
  
205
197
    bzr branch http://bazaar-vcs.org/bzr/bzr.dev/ bzr.dev
206
 
 
 
198
   
207
199
* keep your copy of bzr.dev pristine (by not developing in it) and keep
208
200
  it up to date (by using bzr pull)
209
201
 
230
222
 
231
223
README
232
224
    This file covers a brief introduction to Bazaar and lists some of its
233
 
    key features.
 
225
    key features. 
234
226
 
235
227
NEWS
236
 
    Summary of changes in each Bazaar release that can affect users or
 
228
    Summary of changes in each Bazaar release that can affect users or 
237
229
    plugin developers.
238
230
 
239
231
setup.py
245
237
    with this but don't be confused by it. The build process puts a copy
246
238
    of the main code base into this build directory, along with some other
247
239
    files. You don't need to go in here for anything discussed in this
248
 
    guide.
 
240
    guide. 
249
241
 
250
242
bzrlib
251
243
    Possibly the most exciting folder of all, bzrlib holds the main code
256
248
    Holds documentation on a whole range of things on Bazaar from the
257
249
    origination of ideas within the project to information on Bazaar
258
250
    features and use cases.  Within this directory there is a subdirectory
259
 
    for each translation into a human language.  All the documentation
 
251
    for each translation into a human language.  All the documentation 
260
252
    is in the ReStructuredText markup language.
261
253
 
262
 
doc/developers
 
254
doc/developers 
263
255
    Documentation specifically targeted at Bazaar and plugin developers.
264
256
    (Including this document.)
265
 
 
266
 
 
267
 
 
268
 
Automatically-generated API reference information is available at
269
 
<http://starship.python.net/crew/mwh/bzrlibapi/>.
 
257
    
 
258
        
 
259
 
 
260
Automatically-generated API reference information is available at 
 
261
<http://starship.python.net/crew/mwh/bzrlibapi/>.  
270
262
 
271
263
See also the `Bazaar Architectural Overview
272
264
<http://doc.bazaar-vcs.org/developers/overview.html>`_.
299
291
 
300
292
* **how** this change achieves this purpose
301
293
 
302
 
* anything else you may have fixed in passing
 
294
* anything else you may have fixed in passing 
303
295
 
304
296
* anything significant that you thought of doing, such as a more
305
297
  extensive fix or a different approach, but didn't or couldn't do now
344
336
welcome that only cleanup the code without changing the external
345
337
behaviour.  The core developers take care to keep the code quality high
346
338
and understandable while recognising that perfect is sometimes the enemy
347
 
of good.
 
339
of good. 
348
340
 
349
341
It is easy for reviews to make people notice other things which should be
350
342
fixed but those things should not hold up the original fix being accepted.
386
378
====================
387
379
 
388
380
From May 2009 on, we prefer people to propose code reviews through
389
 
Launchpad.
 
381
Launchpad.  
390
382
 
391
383
 * <https://launchpad.net/+tour/code-review>
392
384
 
411
403
Then go to the branch's web page, which in this case would be
412
404
<https://code.launchpad.net/~mbp/bzr/doc>.  You can simplify this step by just
413
405
running ::
414
 
 
 
406
 
415
407
  bzr lp-open
416
408
 
417
409
You can then click "Propose for merging into another branch", and enter your
433
425
You can generate a merge request like this::
434
426
 
435
427
  bzr send -o bug-1234.diff
436
 
 
 
428
  
437
429
``bzr send`` can also send mail directly if you prefer; see the help.
438
430
 
439
431
Reviewing changes
465
457
You can generate a merge request like this::
466
458
 
467
459
  bzr send -o bug-1234.patch
468
 
 
 
460
  
469
461
A ``.patch`` extension is recommended instead of .bundle as many mail clients
470
462
will send the latter as a binary file.
471
463
 
520
512
Code layout
521
513
===========
522
514
 
523
 
Please write PEP-8__ compliant code.
 
515
Please write PEP-8__ compliant code.  
524
516
 
525
517
__ http://www.python.org/peps/pep-0008.html
526
518
 
538
530
Each file must have a newline at the end of it.
539
531
 
540
532
Lines should be no more than 79 characters if at all possible.
541
 
Lines that continue a long statement may be indented in either of
 
533
Lines that continue a long statement may be indented in either of 
542
534
two ways:
543
535
 
544
536
within the parenthesis or other character that opens the block, e.g.::
628
620
Naming
629
621
======
630
622
 
631
 
Functions, methods or members that are relatively private are given
 
623
Functions, methods or members that are "private" to bzrlib are given
632
624
a leading underscore prefix.  Names without a leading underscore are
633
625
public not just across modules but to programmers using bzrlib as an
634
 
API.
 
626
API. As a consequence, a leading underscore is appropriate for names
 
627
exposed across modules but that are not to be exposed to bzrlib API
 
628
programmers.
635
629
 
636
630
We prefer class names to be concatenated capital words (``TestCase``)
637
631
and variables, methods and functions to be lowercase words joined by
679
673
    may not catch every case but it's still useful sometimes.
680
674
 
681
675
 
682
 
Cleanup methods
683
 
===============
684
 
 
685
 
Often when something has failed later code, including cleanups invoked
686
 
from ``finally`` blocks, will fail too.  These secondary failures are
687
 
generally uninteresting compared to the original exception.  So use the
688
 
``only_raises`` decorator (from ``bzrlib.decorators``) for methods that
689
 
are typically called in ``finally`` blocks, such as ``unlock`` methods.
690
 
For example, ``@only_raises(LockNotHeld, LockBroken)``.  All errors that
691
 
are unlikely to be a knock-on failure from a previous failure should be
692
 
allowed.
693
 
 
694
 
 
695
676
Factories
696
677
=========
697
678
 
698
679
In some places we have variables which point to callables that construct
699
680
new instances.  That is to say, they can be used a lot like class objects,
700
 
but they shouldn't be *named* like classes::
 
681
but they shouldn't be *named* like classes:
701
682
 
702
683
> I think that things named FooBar should create instances of FooBar when
703
684
> called. Its plain confusing for them to do otherwise. When we have
710
691
Registries
711
692
==========
712
693
 
713
 
Several places in Bazaar use (or will use) a registry, which is a
714
 
mapping from names to objects or classes.  The registry allows for
 
694
Several places in Bazaar use (or will use) a registry, which is a 
 
695
mapping from names to objects or classes.  The registry allows for 
715
696
loading in registered code only when it's needed, and keeping
716
697
associated information such as a help string or description.
717
698
 
721
702
 
722
703
The ``InterObject`` provides for two-way `multiple dispatch`__: matching
723
704
up for example a source and destination repository to find the right way
724
 
to transfer data between them.
 
705
to transfer data between them. 
725
706
 
726
707
.. __: http://en.wikipedia.org/wiki/Multiple_dispatch
727
708
 
728
709
There is a subclass ``InterObject`` classes for each type of object that is
729
710
dispatched this way, e.g. ``InterRepository``.  Calling ``.get()`` on this
730
 
class will return an ``InterObject`` instance providing the best match for
 
711
class will return an ``InterObject`` instance providing the best match for 
731
712
those parameters, and this instance then has methods for operations
732
713
between the objects.
733
714
 
734
 
::
735
 
 
736
715
  inter = InterRepository.get(source_repo, target_repo)
737
716
  inter.fetch(revision_id)
738
717
 
816
795
 
817
796
If you add a new class you should generally add a ``__repr__`` method
818
797
unless there is an adequate method in a parent class.  There should be a
819
 
test for the repr.
 
798
test for the repr.  
820
799
 
821
800
Representations should typically look like Python constructor syntax, but
822
801
they don't need to include every value in the object and they don't need
868
847
Evolving Interfaces
869
848
===================
870
849
 
871
 
We don't change APIs in stable branches: any supported symbol in a stable
872
 
release of bzr must not be altered in any way that would result in
 
850
We have a commitment to 6 months API stability - any supported symbol in a
 
851
release of bzr MUST NOT be altered in any way that would result in
873
852
breaking existing code that uses it. That means that method names,
874
853
parameter ordering, parameter names, variable and attribute names etc must
875
854
not be changed without leaving a 'deprecated forwarder' behind. This even
879
858
way, you need to change its name as well. For instance, if I add an optional keyword
880
859
parameter to branch.commit - that's fine. On the other hand, if I add a
881
860
keyword parameter to branch.commit which is a *required* transaction
882
 
object, I should rename the API - i.e. to 'branch.commit_transaction'.
883
 
 
884
 
  (Actually, that may break code that provides a new implementation of
885
 
  ``commit`` and doesn't expect to receive the parameter.)
 
861
object, I should rename the API - i.e. to 'branch.commit_transaction'. 
886
862
 
887
863
When renaming such supported API's, be sure to leave a deprecated_method (or
888
864
_function or ...) behind which forwards to the new API. See the
1021
997
time until the finally block runs.
1022
998
 
1023
999
 
1024
 
Message guidelines
1025
 
------------------
1026
 
 
1027
 
When filenames or similar variables are presented inline within a message,
1028
 
they should be enclosed in double quotes (ascii 0x22, not chiral unicode
1029
 
quotes)::
1030
 
 
1031
 
  bzr: ERROR: No such file "asdf"
1032
 
 
1033
 
When we print just a list of filenames there should not be any quoting:
1034
 
see `bug 544297`_.
1035
 
 
1036
 
.. _bug 544297: https://bugs.launchpad.net/bugs/544297
1037
 
 
1038
 
https://wiki.ubuntu.com/UnitsPolicy provides a good explanation about
1039
 
which unit should be used when. Roughly speaking, IEC standard applies
1040
 
for base-2 units and SI standard applies for base-10 units:
1041
 
 
1042
 
* for network bandwidth and disk sizes, use base-10 (Mbits/s, kB/s, GB)
1043
 
 
1044
 
* for RAM sizes, use base-2 (GiB, TiB)
1045
 
 
1046
 
 
1047
 
 
1048
1000
Displaying help
1049
1001
===============
1050
1002
 
1073
1025
 
1074
1026
    0. OK.
1075
1027
    1. Conflicts in merge-like operations, or changes are present in
1076
 
       diff-like operations.
1077
 
    2. Unrepresentable diff changes (i.e. binary files that we cannot show
 
1028
       diff-like operations. 
 
1029
    2. Unrepresentable diff changes (i.e. binary files that we cannot show 
1078
1030
       a diff of).
1079
1031
    3. An error or exception has occurred.
1080
1032
    4. An internal error occurred (one that shows a traceback.)
1111
1063
format string.
1112
1064
 
1113
1065
#. If it is something that a caller can recover from, a custom exception
1114
 
   is reasonable.
 
1066
   is reasonable. 
1115
1067
 
1116
1068
#. If it is a data consistency issue, using a builtin like
1117
 
   ``ValueError``/``TypeError`` is reasonable.
 
1069
   ``ValueError``/``TypeError`` is reasonable. 
1118
1070
 
1119
1071
#. If it is a programmer error (using an api incorrectly)
1120
 
   ``AssertionError`` is reasonable.
 
1072
   ``AssertionError`` is reasonable. 
1121
1073
 
1122
1074
#. Otherwise, use ``BzrError`` or ``InternalBzrError``.
1123
1075
 
1176
1128
Within each release, entries in the news file should have the most
1177
1129
user-visible changes first.  So the order should be approximately:
1178
1130
 
1179
 
 * changes to existing behaviour - the highest priority because the
 
1131
 * changes to existing behaviour - the highest priority because the 
1180
1132
   user's existing knowledge is incorrect
1181
1133
 * new features - should be brought to their attention
1182
1134
 * bug fixes - may be of interest if the bug was affecting them, and
1183
1135
   should include the bug number if any
1184
 
 * major documentation changes, including fixed documentation bugs
 
1136
 * major documentation changes
1185
1137
 * changes to internal interfaces
1186
1138
 
1187
1139
People who made significant contributions to each change are listed in
1188
1140
parenthesis.  This can include reporting bugs (particularly with good
1189
1141
details or reproduction recipes), submitting patches, etc.
1190
1142
 
1191
 
To help with merging, NEWS entries should be sorted lexicographically
1192
 
within each section.
1193
 
 
1194
1143
Commands
1195
1144
--------
1196
1145
 
1204
1153
-----------------
1205
1154
 
1206
1155
Functions, methods, classes and modules should have docstrings
1207
 
describing how they are used.
 
1156
describing how they are used. 
1208
1157
 
1209
1158
The first line of the docstring should be a self-contained sentence.
1210
1159
 
1235
1184
    We had the problem that lots of our files were "Copyright Canonical
1236
1185
    Development Ltd" which is not a real company, and some other variations
1237
1186
    on this theme. Also, some files were missing the GPL statements.
1238
 
 
 
1187
    
1239
1188
    I want to be clear about the intent of this patch, since copyright can
1240
1189
    be a little controversial.
1241
 
 
 
1190
    
1242
1191
    1) The big motivation for this is not to shut out the community, but
1243
1192
    just to clean up all of the invalid copyright statements.
1244
 
 
 
1193
    
1245
1194
    2) It has been the general policy for bzr that we want a single
1246
1195
    copyright holder for all of the core code. This is following the model
1247
1196
    set by the FSF, which makes it easier to update the code to a new
1254
1203
    I'm sure Canonical would do the same).
1255
1204
    As such, Canonical has requested copyright assignments from all of the
1256
1205
    major contributers.
1257
 
 
 
1206
    
1258
1207
    3) If someone wants to add code and not attribute it to Canonical, there
1259
1208
    is a specific list of files that are excluded from this check. And the
1260
1209
    test failure indicates where that is, and how to update it.
1261
 
 
 
1210
    
1262
1211
    4) If anyone feels that I changed a copyright statement incorrectly, just
1263
1212
    let me know, and I'll be happy to correct it. Whenever you have large
1264
1213
    mechanical changes like this, it is possible to make some mistakes.
1265
 
 
 
1214
    
1266
1215
    Just to reiterate, this is a community project, and it is meant to stay
1267
1216
    that way. Core bzr code is copyright Canonical for legal reasons, and
1268
1217
    the tests are just there to help us maintain that.
1279
1228
 
1280
1229
.. _pdb: http://docs.python.org/lib/debugger-commands.html
1281
1230
 
1282
 
If the ``BZR_PDB`` environment variable is set
 
1231
If the ``BZR_PDB`` environment variable is set 
1283
1232
then bzr will go into pdb post-mortem mode when an unhandled exception
1284
1233
occurs.
1285
1234
 
1347
1296
    for automated processing.
1348
1297
    For example: ``bzr log`` should not fail if one of the entries has text
1349
1298
    that cannot be displayed.
1350
 
 
 
1299
  
1351
1300
  strict
1352
1301
    Attempting to print an unprintable character will cause a UnicodeError.
1353
1302
    This is for commands that are intended more as scripting support, rather
1357
1306
    printed a filename with a '?', the wrong file could be deleted. (At the
1358
1307
    very least, the correct file would not be deleted). An error is used to
1359
1308
    indicate that the requested action could not be performed.
1360
 
 
 
1309
  
1361
1310
  exact
1362
1311
    Do not attempt to automatically convert Unicode strings. This is used
1363
1312
    for commands that must handle conversion themselves.
1411
1360
 
1412
1361
To create an extension, add rules to setup.py for building it with pyrex,
1413
1362
and with distutils. Now start with an empty .pyx file. At the top add
1414
 
"include 'yourmodule.py'". This will import the contents of foo.py into this
 
1363
"include 'yourmodule.py'". This will import the contents of foo.py into this 
1415
1364
file at build time - remember that only one module will be loaded at
1416
1365
runtime. Now you can subclass classes, or replace functions, and only your
1417
1366
changes need to be present in the .pyx file.
1418
1367
 
1419
1368
Note that pyrex does not support all 2.4 programming idioms, so some
1420
 
syntax changes may be required. I.e.
 
1369
syntax changes may be required. I.e. 
1421
1370
 
1422
 
 - 'from foo import (bar, gam)' needs to change to not use the brackets.
1423
 
 - 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar'
 
1371
 - 'from foo import (bar, gam)' needs to change to not use the brackets. 
 
1372
 - 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar' 
1424
1373
 
1425
1374
If the changes are too dramatic, consider
1426
1375
maintaining the python code twice - once in the .pyx, and once in the .py,
1703
1652
.. note::
1704
1653
  As well as prioritizing bugs and nominating them against a
1705
1654
  target milestone, Launchpad lets core developers offer to mentor others in
1706
 
  fixing them.
 
1655
  fixing them. 
1707
1656
 
1708
1657
 
1709
1658
..