← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/HACKING.txt

  • Committer: Andrew Bennetts
  • Date: 2010-02-12 04:33:05 UTC
  • mfrom: (5031 +trunk)
  • mto: This revision was merged to the branch mainline in revision 5032.
  • Revision ID: andrew.bennetts@canonical.com-20100212043305-ujdbsdoviql2t7i3
Merge lp:bzr

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 on others, saving time
 
65
* you get to build on the wisdom of 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/giveback
 
123
  $ bzr push lp:~your_lp_username/bzr/meaningful_name_here
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 <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.
 
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
 
129
137
 
130
138
Why make a local copy of bzr.dev?
131
139
---------------------------------
133
141
Making a local mirror of bzr.dev is not strictly necessary, but it means
134
142
 
135
143
- You can use that copy of bzr.dev as your main bzr executable, and keep it
136
 
  up-to-date using ``bzr pull``.  
 
144
  up-to-date using ``bzr pull``.
137
145
- Certain operations are faster, and can be done when offline.  For example:
138
146
 
139
147
  - ``bzr bundle``
140
148
  - ``bzr diff -r ancestor:...``
141
149
  - ``bzr merge``
142
150
 
143
 
- When it's time to create your next branch, it's more convenient.  When you 
 
151
- When it's time to create your next branch, it's more convenient.  When you
144
152
  have further contributions to make, you should do them in their own branch::
145
153
 
146
154
    $ cd ~/bzr
193
201
 
194
202
* create a local copy of the main development branch (bzr.dev) by using
195
203
  this command::
196
 
  
 
204
 
197
205
    bzr branch http://bazaar-vcs.org/bzr/bzr.dev/ bzr.dev
198
 
   
 
206
 
199
207
* keep your copy of bzr.dev pristine (by not developing in it) and keep
200
208
  it up to date (by using bzr pull)
201
209
 
222
230
 
223
231
README
224
232
    This file covers a brief introduction to Bazaar and lists some of its
225
 
    key features. 
 
233
    key features.
226
234
 
227
235
NEWS
228
 
    Summary of changes in each Bazaar release that can affect users or 
 
236
    Summary of changes in each Bazaar release that can affect users or
229
237
    plugin developers.
230
238
 
231
239
setup.py
237
245
    with this but don't be confused by it. The build process puts a copy
238
246
    of the main code base into this build directory, along with some other
239
247
    files. You don't need to go in here for anything discussed in this
240
 
    guide. 
 
248
    guide.
241
249
 
242
250
bzrlib
243
251
    Possibly the most exciting folder of all, bzrlib holds the main code
248
256
    Holds documentation on a whole range of things on Bazaar from the
249
257
    origination of ideas within the project to information on Bazaar
250
258
    features and use cases.  Within this directory there is a subdirectory
251
 
    for each translation into a human language.  All the documentation 
 
259
    for each translation into a human language.  All the documentation
252
260
    is in the ReStructuredText markup language.
253
261
 
254
 
doc/developers 
 
262
doc/developers
255
263
    Documentation specifically targeted at Bazaar and plugin developers.
256
264
    (Including this document.)
257
 
    
258
 
        
259
 
 
260
 
Automatically-generated API reference information is available at 
261
 
<http://starship.python.net/crew/mwh/bzrlibapi/>.  
 
265
 
 
266
 
 
267
 
 
268
Automatically-generated API reference information is available at
 
269
<http://starship.python.net/crew/mwh/bzrlibapi/>.
262
270
 
263
271
See also the `Bazaar Architectural Overview
264
272
<http://doc.bazaar-vcs.org/developers/overview.html>`_.
291
299
 
292
300
* **how** this change achieves this purpose
293
301
 
294
 
* anything else you may have fixed in passing 
 
302
* anything else you may have fixed in passing
295
303
 
296
304
* anything significant that you thought of doing, such as a more
297
305
  extensive fix or a different approach, but didn't or couldn't do now
336
344
welcome that only cleanup the code without changing the external
337
345
behaviour.  The core developers take care to keep the code quality high
338
346
and understandable while recognising that perfect is sometimes the enemy
339
 
of good. 
 
347
of good.
340
348
 
341
349
It is easy for reviews to make people notice other things which should be
342
350
fixed but those things should not hold up the original fix being accepted.
378
386
====================
379
387
 
380
388
From May 2009 on, we prefer people to propose code reviews through
381
 
Launchpad.  
 
389
Launchpad.
382
390
 
383
391
 * <https://launchpad.net/+tour/code-review>
384
392
 
403
411
Then go to the branch's web page, which in this case would be
404
412
<https://code.launchpad.net/~mbp/bzr/doc>.  You can simplify this step by just
405
413
running ::
406
 
 
 
414
 
407
415
  bzr lp-open
408
416
 
409
417
You can then click "Propose for merging into another branch", and enter your
425
433
You can generate a merge request like this::
426
434
 
427
435
  bzr send -o bug-1234.diff
428
 
  
 
436
 
429
437
``bzr send`` can also send mail directly if you prefer; see the help.
430
438
 
431
439
Reviewing changes
457
465
You can generate a merge request like this::
458
466
 
459
467
  bzr send -o bug-1234.patch
460
 
  
 
468
 
461
469
A ``.patch`` extension is recommended instead of .bundle as many mail clients
462
470
will send the latter as a binary file.
463
471
 
512
520
Code layout
513
521
===========
514
522
 
515
 
Please write PEP-8__ compliant code.  
 
523
Please write PEP-8__ compliant code.
516
524
 
517
525
__ http://www.python.org/peps/pep-0008.html
518
526
 
530
538
Each file must have a newline at the end of it.
531
539
 
532
540
Lines should be no more than 79 characters if at all possible.
533
 
Lines that continue a long statement may be indented in either of 
 
541
Lines that continue a long statement may be indented in either of
534
542
two ways:
535
543
 
536
544
within the parenthesis or other character that opens the block, e.g.::
623
631
Functions, methods or members that are relatively private are given
624
632
a leading underscore prefix.  Names without a leading underscore are
625
633
public not just across modules but to programmers using bzrlib as an
626
 
API. 
 
634
API.
627
635
 
628
636
We prefer class names to be concatenated capital words (``TestCase``)
629
637
and variables, methods and functions to be lowercase words joined by
680
688
``only_raises`` decorator (from ``bzrlib.decorators``) for methods that
681
689
are typically called in ``finally`` blocks, such as ``unlock`` methods.
682
690
For example, ``@only_raises(LockNotHeld, LockBroken)``.  All errors that
683
 
are unlikely to be a knock-on failure from an previous failure should be
 
691
are unlikely to be a knock-on failure from a previous failure should be
684
692
allowed.
685
693
 
686
694
 
689
697
 
690
698
In some places we have variables which point to callables that construct
691
699
new instances.  That is to say, they can be used a lot like class objects,
692
 
but they shouldn't be *named* like classes:
 
700
but they shouldn't be *named* like classes::
693
701
 
694
702
> I think that things named FooBar should create instances of FooBar when
695
703
> called. Its plain confusing for them to do otherwise. When we have
702
710
Registries
703
711
==========
704
712
 
705
 
Several places in Bazaar use (or will use) a registry, which is a 
706
 
mapping from names to objects or classes.  The registry allows for 
 
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
707
715
loading in registered code only when it's needed, and keeping
708
716
associated information such as a help string or description.
709
717
 
713
721
 
714
722
The ``InterObject`` provides for two-way `multiple dispatch`__: matching
715
723
up for example a source and destination repository to find the right way
716
 
to transfer data between them. 
 
724
to transfer data between them.
717
725
 
718
726
.. __: http://en.wikipedia.org/wiki/Multiple_dispatch
719
727
 
720
728
There is a subclass ``InterObject`` classes for each type of object that is
721
729
dispatched this way, e.g. ``InterRepository``.  Calling ``.get()`` on this
722
 
class will return an ``InterObject`` instance providing the best match for 
 
730
class will return an ``InterObject`` instance providing the best match for
723
731
those parameters, and this instance then has methods for operations
724
732
between the objects.
725
733
 
 
734
::
 
735
 
726
736
  inter = InterRepository.get(source_repo, target_repo)
727
737
  inter.fetch(revision_id)
728
738
 
806
816
 
807
817
If you add a new class you should generally add a ``__repr__`` method
808
818
unless there is an adequate method in a parent class.  There should be a
809
 
test for the repr.  
 
819
test for the repr.
810
820
 
811
821
Representations should typically look like Python constructor syntax, but
812
822
they don't need to include every value in the object and they don't need
869
879
way, you need to change its name as well. For instance, if I add an optional keyword
870
880
parameter to branch.commit - that's fine. On the other hand, if I add a
871
881
keyword parameter to branch.commit which is a *required* transaction
872
 
object, I should rename the API - i.e. to 'branch.commit_transaction'. 
 
882
object, I should rename the API - i.e. to 'branch.commit_transaction'.
873
883
 
874
884
  (Actually, that may break code that provides a new implementation of
875
885
  ``commit`` and doesn't expect to receive the parameter.)
1010
1020
finish the progress task when it exits, because it may otherwise be a long
1011
1021
time until the finally block runs.
1012
1022
 
 
1023
https://wiki.ubuntu.com/UnitsPolicy provides a good explanation about
 
1024
which unit should be used when. Roughly speaking, IEC standard applies
 
1025
for base-2 units and SI standard applies for base-10 units::
 
1026
* for network bandwidth an disk sizes, use base-10 (Mbits/s, kB/s, GB),
 
1027
* for RAM sizes, use base-2 (GiB, TiB).
 
1028
 
1013
1029
 
1014
1030
Displaying help
1015
1031
===============
1039
1055
 
1040
1056
    0. OK.
1041
1057
    1. Conflicts in merge-like operations, or changes are present in
1042
 
       diff-like operations. 
1043
 
    2. Unrepresentable diff changes (i.e. binary files that we cannot show 
 
1058
       diff-like operations.
 
1059
    2. Unrepresentable diff changes (i.e. binary files that we cannot show
1044
1060
       a diff of).
1045
1061
    3. An error or exception has occurred.
1046
1062
    4. An internal error occurred (one that shows a traceback.)
1077
1093
format string.
1078
1094
 
1079
1095
#. If it is something that a caller can recover from, a custom exception
1080
 
   is reasonable. 
 
1096
   is reasonable.
1081
1097
 
1082
1098
#. If it is a data consistency issue, using a builtin like
1083
 
   ``ValueError``/``TypeError`` is reasonable. 
 
1099
   ``ValueError``/``TypeError`` is reasonable.
1084
1100
 
1085
1101
#. If it is a programmer error (using an api incorrectly)
1086
 
   ``AssertionError`` is reasonable. 
 
1102
   ``AssertionError`` is reasonable.
1087
1103
 
1088
1104
#. Otherwise, use ``BzrError`` or ``InternalBzrError``.
1089
1105
 
1142
1158
Within each release, entries in the news file should have the most
1143
1159
user-visible changes first.  So the order should be approximately:
1144
1160
 
1145
 
 * changes to existing behaviour - the highest priority because the 
 
1161
 * changes to existing behaviour - the highest priority because the
1146
1162
   user's existing knowledge is incorrect
1147
1163
 * new features - should be brought to their attention
1148
1164
 * bug fixes - may be of interest if the bug was affecting them, and
1149
1165
   should include the bug number if any
1150
 
 * major documentation changes
 
1166
 * major documentation changes, including fixed documentation bugs
1151
1167
 * changes to internal interfaces
1152
1168
 
1153
1169
People who made significant contributions to each change are listed in
1154
1170
parenthesis.  This can include reporting bugs (particularly with good
1155
1171
details or reproduction recipes), submitting patches, etc.
1156
1172
 
 
1173
To help with merging, NEWS entries should be sorted lexicographically
 
1174
within each section.
 
1175
 
1157
1176
Commands
1158
1177
--------
1159
1178
 
1167
1186
-----------------
1168
1187
 
1169
1188
Functions, methods, classes and modules should have docstrings
1170
 
describing how they are used. 
 
1189
describing how they are used.
1171
1190
 
1172
1191
The first line of the docstring should be a self-contained sentence.
1173
1192
 
1198
1217
    We had the problem that lots of our files were "Copyright Canonical
1199
1218
    Development Ltd" which is not a real company, and some other variations
1200
1219
    on this theme. Also, some files were missing the GPL statements.
1201
 
    
 
1220
 
1202
1221
    I want to be clear about the intent of this patch, since copyright can
1203
1222
    be a little controversial.
1204
 
    
 
1223
 
1205
1224
    1) The big motivation for this is not to shut out the community, but
1206
1225
    just to clean up all of the invalid copyright statements.
1207
 
    
 
1226
 
1208
1227
    2) It has been the general policy for bzr that we want a single
1209
1228
    copyright holder for all of the core code. This is following the model
1210
1229
    set by the FSF, which makes it easier to update the code to a new
1217
1236
    I'm sure Canonical would do the same).
1218
1237
    As such, Canonical has requested copyright assignments from all of the
1219
1238
    major contributers.
1220
 
    
 
1239
 
1221
1240
    3) If someone wants to add code and not attribute it to Canonical, there
1222
1241
    is a specific list of files that are excluded from this check. And the
1223
1242
    test failure indicates where that is, and how to update it.
1224
 
    
 
1243
 
1225
1244
    4) If anyone feels that I changed a copyright statement incorrectly, just
1226
1245
    let me know, and I'll be happy to correct it. Whenever you have large
1227
1246
    mechanical changes like this, it is possible to make some mistakes.
1228
 
    
 
1247
 
1229
1248
    Just to reiterate, this is a community project, and it is meant to stay
1230
1249
    that way. Core bzr code is copyright Canonical for legal reasons, and
1231
1250
    the tests are just there to help us maintain that.
1242
1261
 
1243
1262
.. _pdb: http://docs.python.org/lib/debugger-commands.html
1244
1263
 
1245
 
If the ``BZR_PDB`` environment variable is set 
 
1264
If the ``BZR_PDB`` environment variable is set
1246
1265
then bzr will go into pdb post-mortem mode when an unhandled exception
1247
1266
occurs.
1248
1267
 
1310
1329
    for automated processing.
1311
1330
    For example: ``bzr log`` should not fail if one of the entries has text
1312
1331
    that cannot be displayed.
1313
 
  
 
1332
 
1314
1333
  strict
1315
1334
    Attempting to print an unprintable character will cause a UnicodeError.
1316
1335
    This is for commands that are intended more as scripting support, rather
1320
1339
    printed a filename with a '?', the wrong file could be deleted. (At the
1321
1340
    very least, the correct file would not be deleted). An error is used to
1322
1341
    indicate that the requested action could not be performed.
1323
 
  
 
1342
 
1324
1343
  exact
1325
1344
    Do not attempt to automatically convert Unicode strings. This is used
1326
1345
    for commands that must handle conversion themselves.
1374
1393
 
1375
1394
To create an extension, add rules to setup.py for building it with pyrex,
1376
1395
and with distutils. Now start with an empty .pyx file. At the top add
1377
 
"include 'yourmodule.py'". This will import the contents of foo.py into this 
 
1396
"include 'yourmodule.py'". This will import the contents of foo.py into this
1378
1397
file at build time - remember that only one module will be loaded at
1379
1398
runtime. Now you can subclass classes, or replace functions, and only your
1380
1399
changes need to be present in the .pyx file.
1381
1400
 
1382
1401
Note that pyrex does not support all 2.4 programming idioms, so some
1383
 
syntax changes may be required. I.e. 
 
1402
syntax changes may be required. I.e.
1384
1403
 
1385
 
 - 'from foo import (bar, gam)' needs to change to not use the brackets. 
1386
 
 - 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar' 
 
1404
 - 'from foo import (bar, gam)' needs to change to not use the brackets.
 
1405
 - 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar'
1387
1406
 
1388
1407
If the changes are too dramatic, consider
1389
1408
maintaining the python code twice - once in the .pyx, and once in the .py,
1666
1685
.. note::
1667
1686
  As well as prioritizing bugs and nominating them against a
1668
1687
  target milestone, Launchpad lets core developers offer to mentor others in
1669
 
  fixing them. 
 
1688
  fixing them.
1670
1689
 
1671
1690
 
1672
1691
..