/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/developers/HACKING.txt

  • Committer: John Arbash Meinel
  • Date: 2009-12-10 17:16:19 UTC
  • mfrom: (4884 +trunk)
  • mto: This revision was merged to the branch mainline in revision 4889.
  • Revision ID: john@arbash-meinel.com-20091210171619-ehdcxjbl8afhq9g1
Bring in bzr.dev 4884

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
 
64
64
 
65
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
133
133
Making a local mirror of bzr.dev is not strictly necessary, but it means
134
134
 
135
135
- You can use that copy of bzr.dev as your main bzr executable, and keep it
136
 
  up-to-date using ``bzr pull``.  
 
136
  up-to-date using ``bzr pull``.
137
137
- Certain operations are faster, and can be done when offline.  For example:
138
138
 
139
139
  - ``bzr bundle``
140
140
  - ``bzr diff -r ancestor:...``
141
141
  - ``bzr merge``
142
142
 
143
 
- 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
144
144
  have further contributions to make, you should do them in their own branch::
145
145
 
146
146
    $ cd ~/bzr
193
193
 
194
194
* create a local copy of the main development branch (bzr.dev) by using
195
195
  this command::
196
 
  
 
196
 
197
197
    bzr branch http://bazaar-vcs.org/bzr/bzr.dev/ bzr.dev
198
 
   
 
198
 
199
199
* keep your copy of bzr.dev pristine (by not developing in it) and keep
200
200
  it up to date (by using bzr pull)
201
201
 
222
222
 
223
223
README
224
224
    This file covers a brief introduction to Bazaar and lists some of its
225
 
    key features. 
 
225
    key features.
226
226
 
227
227
NEWS
228
 
    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
229
229
    plugin developers.
230
230
 
231
231
setup.py
237
237
    with this but don't be confused by it. The build process puts a copy
238
238
    of the main code base into this build directory, along with some other
239
239
    files. You don't need to go in here for anything discussed in this
240
 
    guide. 
 
240
    guide.
241
241
 
242
242
bzrlib
243
243
    Possibly the most exciting folder of all, bzrlib holds the main code
248
248
    Holds documentation on a whole range of things on Bazaar from the
249
249
    origination of ideas within the project to information on Bazaar
250
250
    features and use cases.  Within this directory there is a subdirectory
251
 
    for each translation into a human language.  All the documentation 
 
251
    for each translation into a human language.  All the documentation
252
252
    is in the ReStructuredText markup language.
253
253
 
254
 
doc/developers 
 
254
doc/developers
255
255
    Documentation specifically targeted at Bazaar and plugin developers.
256
256
    (Including this document.)
257
 
    
258
 
        
259
 
 
260
 
Automatically-generated API reference information is available at 
261
 
<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/>.
262
262
 
263
263
See also the `Bazaar Architectural Overview
264
264
<http://doc.bazaar-vcs.org/developers/overview.html>`_.
291
291
 
292
292
* **how** this change achieves this purpose
293
293
 
294
 
* anything else you may have fixed in passing 
 
294
* anything else you may have fixed in passing
295
295
 
296
296
* anything significant that you thought of doing, such as a more
297
297
  extensive fix or a different approach, but didn't or couldn't do now
336
336
welcome that only cleanup the code without changing the external
337
337
behaviour.  The core developers take care to keep the code quality high
338
338
and understandable while recognising that perfect is sometimes the enemy
339
 
of good. 
 
339
of good.
340
340
 
341
341
It is easy for reviews to make people notice other things which should be
342
342
fixed but those things should not hold up the original fix being accepted.
378
378
====================
379
379
 
380
380
From May 2009 on, we prefer people to propose code reviews through
381
 
Launchpad.  
 
381
Launchpad.
382
382
 
383
383
 * <https://launchpad.net/+tour/code-review>
384
384
 
403
403
Then go to the branch's web page, which in this case would be
404
404
<https://code.launchpad.net/~mbp/bzr/doc>.  You can simplify this step by just
405
405
running ::
406
 
 
 
406
 
407
407
  bzr lp-open
408
408
 
409
409
You can then click "Propose for merging into another branch", and enter your
425
425
You can generate a merge request like this::
426
426
 
427
427
  bzr send -o bug-1234.diff
428
 
  
 
428
 
429
429
``bzr send`` can also send mail directly if you prefer; see the help.
430
430
 
431
431
Reviewing changes
457
457
You can generate a merge request like this::
458
458
 
459
459
  bzr send -o bug-1234.patch
460
 
  
 
460
 
461
461
A ``.patch`` extension is recommended instead of .bundle as many mail clients
462
462
will send the latter as a binary file.
463
463
 
512
512
Code layout
513
513
===========
514
514
 
515
 
Please write PEP-8__ compliant code.  
 
515
Please write PEP-8__ compliant code.
516
516
 
517
517
__ http://www.python.org/peps/pep-0008.html
518
518
 
530
530
Each file must have a newline at the end of it.
531
531
 
532
532
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 
 
533
Lines that continue a long statement may be indented in either of
534
534
two ways:
535
535
 
536
536
within the parenthesis or other character that opens the block, e.g.::
620
620
Naming
621
621
======
622
622
 
623
 
Functions, methods or members that are "private" to bzrlib are given
 
623
Functions, methods or members that are relatively private are given
624
624
a leading underscore prefix.  Names without a leading underscore are
625
625
public not just across modules but to programmers using bzrlib as an
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.
 
626
API.
629
627
 
630
628
We prefer class names to be concatenated capital words (``TestCase``)
631
629
and variables, methods and functions to be lowercase words joined by
673
671
    may not catch every case but it's still useful sometimes.
674
672
 
675
673
 
 
674
Cleanup methods
 
675
===============
 
676
 
 
677
Often when something has failed later code, including cleanups invoked
 
678
from ``finally`` blocks, will fail too.  These secondary failures are
 
679
generally uninteresting compared to the original exception.  So use the
 
680
``only_raises`` decorator (from ``bzrlib.decorators``) for methods that
 
681
are typically called in ``finally`` blocks, such as ``unlock`` methods.
 
682
For example, ``@only_raises(LockNotHeld, LockBroken)``.  All errors that
 
683
are unlikely to be a knock-on failure from an previous failure should be
 
684
allowed.
 
685
 
 
686
 
676
687
Factories
677
688
=========
678
689
 
691
702
Registries
692
703
==========
693
704
 
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 
 
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
696
707
loading in registered code only when it's needed, and keeping
697
708
associated information such as a help string or description.
698
709
 
702
713
 
703
714
The ``InterObject`` provides for two-way `multiple dispatch`__: matching
704
715
up for example a source and destination repository to find the right way
705
 
to transfer data between them. 
 
716
to transfer data between them.
706
717
 
707
718
.. __: http://en.wikipedia.org/wiki/Multiple_dispatch
708
719
 
709
720
There is a subclass ``InterObject`` classes for each type of object that is
710
721
dispatched this way, e.g. ``InterRepository``.  Calling ``.get()`` on this
711
 
class will return an ``InterObject`` instance providing the best match for 
 
722
class will return an ``InterObject`` instance providing the best match for
712
723
those parameters, and this instance then has methods for operations
713
724
between the objects.
714
725
 
795
806
 
796
807
If you add a new class you should generally add a ``__repr__`` method
797
808
unless there is an adequate method in a parent class.  There should be a
798
 
test for the repr.  
 
809
test for the repr.
799
810
 
800
811
Representations should typically look like Python constructor syntax, but
801
812
they don't need to include every value in the object and they don't need
847
858
Evolving Interfaces
848
859
===================
849
860
 
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
 
861
We don't change APIs in stable branches: any supported symbol in a stable
 
862
release of bzr must not be altered in any way that would result in
852
863
breaking existing code that uses it. That means that method names,
853
864
parameter ordering, parameter names, variable and attribute names etc must
854
865
not be changed without leaving a 'deprecated forwarder' behind. This even
858
869
way, you need to change its name as well. For instance, if I add an optional keyword
859
870
parameter to branch.commit - that's fine. On the other hand, if I add a
860
871
keyword parameter to branch.commit which is a *required* transaction
861
 
object, I should rename the API - i.e. to 'branch.commit_transaction'. 
 
872
object, I should rename the API - i.e. to 'branch.commit_transaction'.
 
873
 
 
874
  (Actually, that may break code that provides a new implementation of
 
875
  ``commit`` and doesn't expect to receive the parameter.)
862
876
 
863
877
When renaming such supported API's, be sure to leave a deprecated_method (or
864
878
_function or ...) behind which forwards to the new API. See the
1025
1039
 
1026
1040
    0. OK.
1027
1041
    1. Conflicts in merge-like operations, or changes are present in
1028
 
       diff-like operations. 
1029
 
    2. Unrepresentable diff changes (i.e. binary files that we cannot show 
 
1042
       diff-like operations.
 
1043
    2. Unrepresentable diff changes (i.e. binary files that we cannot show
1030
1044
       a diff of).
1031
1045
    3. An error or exception has occurred.
1032
1046
    4. An internal error occurred (one that shows a traceback.)
1063
1077
format string.
1064
1078
 
1065
1079
#. If it is something that a caller can recover from, a custom exception
1066
 
   is reasonable. 
 
1080
   is reasonable.
1067
1081
 
1068
1082
#. If it is a data consistency issue, using a builtin like
1069
 
   ``ValueError``/``TypeError`` is reasonable. 
 
1083
   ``ValueError``/``TypeError`` is reasonable.
1070
1084
 
1071
1085
#. If it is a programmer error (using an api incorrectly)
1072
 
   ``AssertionError`` is reasonable. 
 
1086
   ``AssertionError`` is reasonable.
1073
1087
 
1074
1088
#. Otherwise, use ``BzrError`` or ``InternalBzrError``.
1075
1089
 
1128
1142
Within each release, entries in the news file should have the most
1129
1143
user-visible changes first.  So the order should be approximately:
1130
1144
 
1131
 
 * changes to existing behaviour - the highest priority because the 
 
1145
 * changes to existing behaviour - the highest priority because the
1132
1146
   user's existing knowledge is incorrect
1133
1147
 * new features - should be brought to their attention
1134
1148
 * bug fixes - may be of interest if the bug was affecting them, and
1153
1167
-----------------
1154
1168
 
1155
1169
Functions, methods, classes and modules should have docstrings
1156
 
describing how they are used. 
 
1170
describing how they are used.
1157
1171
 
1158
1172
The first line of the docstring should be a self-contained sentence.
1159
1173
 
1184
1198
    We had the problem that lots of our files were "Copyright Canonical
1185
1199
    Development Ltd" which is not a real company, and some other variations
1186
1200
    on this theme. Also, some files were missing the GPL statements.
1187
 
    
 
1201
 
1188
1202
    I want to be clear about the intent of this patch, since copyright can
1189
1203
    be a little controversial.
1190
 
    
 
1204
 
1191
1205
    1) The big motivation for this is not to shut out the community, but
1192
1206
    just to clean up all of the invalid copyright statements.
1193
 
    
 
1207
 
1194
1208
    2) It has been the general policy for bzr that we want a single
1195
1209
    copyright holder for all of the core code. This is following the model
1196
1210
    set by the FSF, which makes it easier to update the code to a new
1203
1217
    I'm sure Canonical would do the same).
1204
1218
    As such, Canonical has requested copyright assignments from all of the
1205
1219
    major contributers.
1206
 
    
 
1220
 
1207
1221
    3) If someone wants to add code and not attribute it to Canonical, there
1208
1222
    is a specific list of files that are excluded from this check. And the
1209
1223
    test failure indicates where that is, and how to update it.
1210
 
    
 
1224
 
1211
1225
    4) If anyone feels that I changed a copyright statement incorrectly, just
1212
1226
    let me know, and I'll be happy to correct it. Whenever you have large
1213
1227
    mechanical changes like this, it is possible to make some mistakes.
1214
 
    
 
1228
 
1215
1229
    Just to reiterate, this is a community project, and it is meant to stay
1216
1230
    that way. Core bzr code is copyright Canonical for legal reasons, and
1217
1231
    the tests are just there to help us maintain that.
1228
1242
 
1229
1243
.. _pdb: http://docs.python.org/lib/debugger-commands.html
1230
1244
 
1231
 
If the ``BZR_PDB`` environment variable is set 
 
1245
If the ``BZR_PDB`` environment variable is set
1232
1246
then bzr will go into pdb post-mortem mode when an unhandled exception
1233
1247
occurs.
1234
1248
 
1296
1310
    for automated processing.
1297
1311
    For example: ``bzr log`` should not fail if one of the entries has text
1298
1312
    that cannot be displayed.
1299
 
  
 
1313
 
1300
1314
  strict
1301
1315
    Attempting to print an unprintable character will cause a UnicodeError.
1302
1316
    This is for commands that are intended more as scripting support, rather
1306
1320
    printed a filename with a '?', the wrong file could be deleted. (At the
1307
1321
    very least, the correct file would not be deleted). An error is used to
1308
1322
    indicate that the requested action could not be performed.
1309
 
  
 
1323
 
1310
1324
  exact
1311
1325
    Do not attempt to automatically convert Unicode strings. This is used
1312
1326
    for commands that must handle conversion themselves.
1360
1374
 
1361
1375
To create an extension, add rules to setup.py for building it with pyrex,
1362
1376
and with distutils. Now start with an empty .pyx file. At the top add
1363
 
"include 'yourmodule.py'". This will import the contents of foo.py into this 
 
1377
"include 'yourmodule.py'". This will import the contents of foo.py into this
1364
1378
file at build time - remember that only one module will be loaded at
1365
1379
runtime. Now you can subclass classes, or replace functions, and only your
1366
1380
changes need to be present in the .pyx file.
1367
1381
 
1368
1382
Note that pyrex does not support all 2.4 programming idioms, so some
1369
 
syntax changes may be required. I.e. 
 
1383
syntax changes may be required. I.e.
1370
1384
 
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' 
 
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'
1373
1387
 
1374
1388
If the changes are too dramatic, consider
1375
1389
maintaining the python code twice - once in the .pyx, and once in the .py,
1652
1666
.. note::
1653
1667
  As well as prioritizing bugs and nominating them against a
1654
1668
  target milestone, Launchpad lets core developers offer to mentor others in
1655
 
  fixing them. 
 
1669
  fixing them.
1656
1670
 
1657
1671
 
1658
1672
..