/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/en/developer-guide/HACKING.txt

  • Committer: Robert Collins
  • Date: 2009-08-20 04:09:58 UTC
  • mto: This revision was merged to the branch mainline in revision 4635.
  • Revision ID: robertc@robertcollins.net-20090820040958-3b3cuuwooz03rnpm
Mark tests that now work as working.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/developer-guide/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
 
11
11
the Bazaar mailing list.  To propose a correction or addition to this
12
12
document, send a merge request or new text to the mailing list.
13
13
 
14
 
The latest developer documentation can be found online at
15
 
http://doc.bazaar-vcs.org/developers/.
 
14
The current version of this document is available in the file 
 
15
``doc/en/developer-guide/HACKING.txt`` in the source tree, or at
 
16
http://doc.bazaar-vcs.org/bzr.dev/en/developer-guide/HACKING.html
 
17
 
 
18
See also:
 
19
`Bazaar Developer Documentation Catalog <../../developers/index.html>`_.
 
20
 
 
21
.. contents::
16
22
 
17
23
 
18
24
Getting Started
62
68
to involving the community before you spend much time on a change.
63
69
These include:
64
70
 
65
 
* you get to build on the wisdom of others, saving time
 
71
* you get to build on the wisdom on others, saving time
66
72
 
67
 
* if others can direct you to similar code, it minimises the work to be done
 
73
* if others can direct you to similar code, it minimises the work to be done 
68
74
 
69
75
* it assists everyone in coordinating direction, priorities and effort.
70
76
 
87
93
-----------------
88
94
 
89
95
First, get a local copy of the development mainline (See `Why make a local
90
 
copy of bzr.dev?`_.)
 
96
copy of bzr.dev?`_.) 
91
97
::
92
98
 
93
99
 $ bzr init-repo ~/bzr
100
106
 
101
107
This will give you a branch called "123456-my-bugfix" that you can work on
102
108
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!).
 
109
Feel free to commit early and often (after all, it's your branch!). 
104
110
 
105
111
Documentation improvements are an easy place to get started giving back to the
106
112
Bazaar project.  The documentation is in the `doc/` subdirectory of the Bazaar
120
126
`your_lp_username`.  You can push your branch to Launchpad directly from
121
127
Bazaar::
122
128
 
123
 
  $ bzr push lp:~your_lp_username/bzr/meaningful_name_here
 
129
  $ bzr push lp:~your_lp_username/bzr/giveback
124
130
 
125
131
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
 
 
 
132
the Bazaar trunk.  Go to <https://launchpad.net/your_lp_username/bzr/giveback>
 
133
and choose "Propose for merging into another branch".  Select "~bzr/bzr/trunk"
 
134
to hand your changes off to the Bazaar developers for review and merging.
137
135
 
138
136
Why make a local copy of bzr.dev?
139
137
---------------------------------
141
139
Making a local mirror of bzr.dev is not strictly necessary, but it means
142
140
 
143
141
- You can use that copy of bzr.dev as your main bzr executable, and keep it
144
 
  up-to-date using ``bzr pull``.
 
142
  up-to-date using ``bzr pull``.  
145
143
- Certain operations are faster, and can be done when offline.  For example:
146
144
 
147
145
  - ``bzr bundle``
148
146
  - ``bzr diff -r ancestor:...``
149
147
  - ``bzr merge``
150
148
 
151
 
- When it's time to create your next branch, it's more convenient.  When you
 
149
- When it's time to create your next branch, it's more convenient.  When you 
152
150
  have further contributions to make, you should do them in their own branch::
153
151
 
154
152
    $ cd ~/bzr
201
199
 
202
200
* create a local copy of the main development branch (bzr.dev) by using
203
201
  this command::
204
 
 
 
202
  
205
203
    bzr branch http://bazaar-vcs.org/bzr/bzr.dev/ bzr.dev
206
 
 
 
204
   
207
205
* keep your copy of bzr.dev pristine (by not developing in it) and keep
208
206
  it up to date (by using bzr pull)
209
207
 
230
228
 
231
229
README
232
230
    This file covers a brief introduction to Bazaar and lists some of its
233
 
    key features.
 
231
    key features. 
234
232
 
235
233
NEWS
236
 
    Summary of changes in each Bazaar release that can affect users or
 
234
    Summary of changes in each Bazaar release that can affect users or 
237
235
    plugin developers.
238
236
 
239
237
setup.py
245
243
    with this but don't be confused by it. The build process puts a copy
246
244
    of the main code base into this build directory, along with some other
247
245
    files. You don't need to go in here for anything discussed in this
248
 
    guide.
 
246
    guide. 
249
247
 
250
248
bzrlib
251
249
    Possibly the most exciting folder of all, bzrlib holds the main code
256
254
    Holds documentation on a whole range of things on Bazaar from the
257
255
    origination of ideas within the project to information on Bazaar
258
256
    features and use cases.  Within this directory there is a subdirectory
259
 
    for each translation into a human language.  All the documentation
 
257
    for each translation into a human language.  All the documentation 
260
258
    is in the ReStructuredText markup language.
261
259
 
262
 
doc/developers
 
260
doc/developers 
263
261
    Documentation specifically targeted at Bazaar and plugin developers.
264
262
    (Including this document.)
265
 
 
266
 
 
267
 
 
268
 
Automatically-generated API reference information is available at
269
 
<http://starship.python.net/crew/mwh/bzrlibapi/>.
270
 
 
271
 
See also the `Bazaar Architectural Overview
272
 
<http://doc.bazaar-vcs.org/developers/overview.html>`_.
 
263
    
 
264
        
 
265
 
 
266
Automatically-generated API reference information is available at 
 
267
<http://starship.python.net/crew/mwh/bzrlibapi/>.  
 
268
 
 
269
See also the `Bazaar Architectural Overview  <../../developers/overview.html>`_.
273
270
 
274
271
 
275
272
The Code Review Process
299
296
 
300
297
* **how** this change achieves this purpose
301
298
 
302
 
* anything else you may have fixed in passing
 
299
* anything else you may have fixed in passing 
303
300
 
304
301
* anything significant that you thought of doing, such as a more
305
302
  extensive fix or a different approach, but didn't or couldn't do now
344
341
welcome that only cleanup the code without changing the external
345
342
behaviour.  The core developers take care to keep the code quality high
346
343
and understandable while recognising that perfect is sometimes the enemy
347
 
of good.
 
344
of good. 
348
345
 
349
346
It is easy for reviews to make people notice other things which should be
350
347
fixed but those things should not hold up the original fix being accepted.
386
383
====================
387
384
 
388
385
From May 2009 on, we prefer people to propose code reviews through
389
 
Launchpad.
 
386
Launchpad.  
390
387
 
391
388
 * <https://launchpad.net/+tour/code-review>
392
389
 
411
408
Then go to the branch's web page, which in this case would be
412
409
<https://code.launchpad.net/~mbp/bzr/doc>.  You can simplify this step by just
413
410
running ::
414
 
 
 
411
 
415
412
  bzr lp-open
416
413
 
417
414
You can then click "Propose for merging into another branch", and enter your
433
430
You can generate a merge request like this::
434
431
 
435
432
  bzr send -o bug-1234.diff
436
 
 
 
433
  
437
434
``bzr send`` can also send mail directly if you prefer; see the help.
438
435
 
439
436
Reviewing changes
465
462
You can generate a merge request like this::
466
463
 
467
464
  bzr send -o bug-1234.patch
468
 
 
 
465
  
469
466
A ``.patch`` extension is recommended instead of .bundle as many mail clients
470
467
will send the latter as a binary file.
471
468
 
520
517
Code layout
521
518
===========
522
519
 
523
 
Please write PEP-8__ compliant code.
 
520
Please write PEP-8__ compliant code.  
524
521
 
525
522
__ http://www.python.org/peps/pep-0008.html
526
523
 
538
535
Each file must have a newline at the end of it.
539
536
 
540
537
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
 
538
Lines that continue a long statement may be indented in either of 
542
539
two ways:
543
540
 
544
541
within the parenthesis or other character that opens the block, e.g.::
628
625
Naming
629
626
======
630
627
 
631
 
Functions, methods or members that are relatively private are given
 
628
Functions, methods or members that are "private" to bzrlib are given
632
629
a leading underscore prefix.  Names without a leading underscore are
633
630
public not just across modules but to programmers using bzrlib as an
634
 
API.
 
631
API. As a consequence, a leading underscore is appropriate for names
 
632
exposed across modules but that are not to be exposed to bzrlib API
 
633
programmers.
635
634
 
636
635
We prefer class names to be concatenated capital words (``TestCase``)
637
636
and variables, methods and functions to be lowercase words joined by
679
678
    may not catch every case but it's still useful sometimes.
680
679
 
681
680
 
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
681
Factories
696
682
=========
697
683
 
698
684
In some places we have variables which point to callables that construct
699
685
new instances.  That is to say, they can be used a lot like class objects,
700
 
but they shouldn't be *named* like classes::
 
686
but they shouldn't be *named* like classes:
701
687
 
702
688
> I think that things named FooBar should create instances of FooBar when
703
689
> called. Its plain confusing for them to do otherwise. When we have
710
696
Registries
711
697
==========
712
698
 
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
 
699
Several places in Bazaar use (or will use) a registry, which is a 
 
700
mapping from names to objects or classes.  The registry allows for 
715
701
loading in registered code only when it's needed, and keeping
716
702
associated information such as a help string or description.
717
703
 
721
707
 
722
708
The ``InterObject`` provides for two-way `multiple dispatch`__: matching
723
709
up for example a source and destination repository to find the right way
724
 
to transfer data between them.
 
710
to transfer data between them. 
725
711
 
726
712
.. __: http://en.wikipedia.org/wiki/Multiple_dispatch
727
713
 
728
714
There is a subclass ``InterObject`` classes for each type of object that is
729
715
dispatched this way, e.g. ``InterRepository``.  Calling ``.get()`` on this
730
 
class will return an ``InterObject`` instance providing the best match for
 
716
class will return an ``InterObject`` instance providing the best match for 
731
717
those parameters, and this instance then has methods for operations
732
718
between the objects.
733
719
 
734
 
::
735
 
 
736
720
  inter = InterRepository.get(source_repo, target_repo)
737
721
  inter.fetch(revision_id)
738
722
 
816
800
 
817
801
If you add a new class you should generally add a ``__repr__`` method
818
802
unless there is an adequate method in a parent class.  There should be a
819
 
test for the repr.
 
803
test for the repr.  
820
804
 
821
805
Representations should typically look like Python constructor syntax, but
822
806
they don't need to include every value in the object and they don't need
857
841
Test coverage
858
842
=============
859
843
 
860
 
All code should be exercised by the test suite.  See the `Bazaar Testing
861
 
Guide <http://doc.bazaar-vcs.org/developers/testing.html>`_ for detailed
862
 
information about writing tests.
 
844
All code should be exercised by the test suite.  See `Guide to Testing
 
845
Bazaar <../../developers/testing.html>`_ for detailed information about writing tests.
863
846
 
864
847
 
865
848
Core Topics
868
851
Evolving Interfaces
869
852
===================
870
853
 
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
 
854
We have a commitment to 6 months API stability - any supported symbol in a
 
855
release of bzr MUST NOT be altered in any way that would result in
873
856
breaking existing code that uses it. That means that method names,
874
857
parameter ordering, parameter names, variable and attribute names etc must
875
858
not be changed without leaving a 'deprecated forwarder' behind. This even
879
862
way, you need to change its name as well. For instance, if I add an optional keyword
880
863
parameter to branch.commit - that's fine. On the other hand, if I add a
881
864
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.)
 
865
object, I should rename the API - i.e. to 'branch.commit_transaction'. 
886
866
 
887
867
When renaming such supported API's, be sure to leave a deprecated_method (or
888
868
_function or ...) behind which forwards to the new API. See the
1021
1001
time until the finally block runs.
1022
1002
 
1023
1003
 
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
1004
Displaying help
1049
1005
===============
1050
1006
 
1053
1009
and on other help topics.  (See ``help_topics.py``.)
1054
1010
 
1055
1011
As for python docstrings, the first paragraph should be a single-sentence
1056
 
synopsis of the command. These are user-visible and should be prefixed with
1057
 
``__doc__ =`` so help works under ``python -OO`` with docstrings stripped.
 
1012
synopsis of the command.
1058
1013
 
1059
1014
The help for options should be one or more proper sentences, starting with
1060
1015
a capital letter and finishing with a full stop (period).
1074
1029
 
1075
1030
    0. OK.
1076
1031
    1. Conflicts in merge-like operations, or changes are present in
1077
 
       diff-like operations.
1078
 
    2. Unrepresentable diff changes (i.e. binary files that we cannot show
 
1032
       diff-like operations. 
 
1033
    2. Unrepresentable diff changes (i.e. binary files that we cannot show 
1079
1034
       a diff of).
1080
1035
    3. An error or exception has occurred.
1081
1036
    4. An internal error occurred (one that shows a traceback.)
1112
1067
format string.
1113
1068
 
1114
1069
#. If it is something that a caller can recover from, a custom exception
1115
 
   is reasonable.
 
1070
   is reasonable. 
1116
1071
 
1117
1072
#. If it is a data consistency issue, using a builtin like
1118
 
   ``ValueError``/``TypeError`` is reasonable.
 
1073
   ``ValueError``/``TypeError`` is reasonable. 
1119
1074
 
1120
1075
#. If it is a programmer error (using an api incorrectly)
1121
 
   ``AssertionError`` is reasonable.
 
1076
   ``AssertionError`` is reasonable. 
1122
1077
 
1123
1078
#. Otherwise, use ``BzrError`` or ``InternalBzrError``.
1124
1079
 
1177
1132
Within each release, entries in the news file should have the most
1178
1133
user-visible changes first.  So the order should be approximately:
1179
1134
 
1180
 
 * changes to existing behaviour - the highest priority because the
 
1135
 * changes to existing behaviour - the highest priority because the 
1181
1136
   user's existing knowledge is incorrect
1182
1137
 * new features - should be brought to their attention
1183
1138
 * bug fixes - may be of interest if the bug was affecting them, and
1184
1139
   should include the bug number if any
1185
 
 * major documentation changes, including fixed documentation bugs
 
1140
 * major documentation changes
1186
1141
 * changes to internal interfaces
1187
1142
 
1188
1143
People who made significant contributions to each change are listed in
1189
1144
parenthesis.  This can include reporting bugs (particularly with good
1190
1145
details or reproduction recipes), submitting patches, etc.
1191
1146
 
1192
 
To help with merging, NEWS entries should be sorted lexicographically
1193
 
within each section.
1194
 
 
1195
1147
Commands
1196
1148
--------
1197
1149
 
1205
1157
-----------------
1206
1158
 
1207
1159
Functions, methods, classes and modules should have docstrings
1208
 
describing how they are used.
 
1160
describing how they are used. 
1209
1161
 
1210
1162
The first line of the docstring should be a self-contained sentence.
1211
1163
 
1236
1188
    We had the problem that lots of our files were "Copyright Canonical
1237
1189
    Development Ltd" which is not a real company, and some other variations
1238
1190
    on this theme. Also, some files were missing the GPL statements.
1239
 
 
 
1191
    
1240
1192
    I want to be clear about the intent of this patch, since copyright can
1241
1193
    be a little controversial.
1242
 
 
 
1194
    
1243
1195
    1) The big motivation for this is not to shut out the community, but
1244
1196
    just to clean up all of the invalid copyright statements.
1245
 
 
 
1197
    
1246
1198
    2) It has been the general policy for bzr that we want a single
1247
1199
    copyright holder for all of the core code. This is following the model
1248
1200
    set by the FSF, which makes it easier to update the code to a new
1255
1207
    I'm sure Canonical would do the same).
1256
1208
    As such, Canonical has requested copyright assignments from all of the
1257
1209
    major contributers.
1258
 
 
 
1210
    
1259
1211
    3) If someone wants to add code and not attribute it to Canonical, there
1260
1212
    is a specific list of files that are excluded from this check. And the
1261
1213
    test failure indicates where that is, and how to update it.
1262
 
 
 
1214
    
1263
1215
    4) If anyone feels that I changed a copyright statement incorrectly, just
1264
1216
    let me know, and I'll be happy to correct it. Whenever you have large
1265
1217
    mechanical changes like this, it is possible to make some mistakes.
1266
 
 
 
1218
    
1267
1219
    Just to reiterate, this is a community project, and it is meant to stay
1268
1220
    that way. Core bzr code is copyright Canonical for legal reasons, and
1269
1221
    the tests are just there to help us maintain that.
1280
1232
 
1281
1233
.. _pdb: http://docs.python.org/lib/debugger-commands.html
1282
1234
 
1283
 
If the ``BZR_PDB`` environment variable is set
 
1235
If the ``BZR_PDB`` environment variable is set 
1284
1236
then bzr will go into pdb post-mortem mode when an unhandled exception
1285
1237
occurs.
1286
1238
 
1348
1300
    for automated processing.
1349
1301
    For example: ``bzr log`` should not fail if one of the entries has text
1350
1302
    that cannot be displayed.
1351
 
 
 
1303
  
1352
1304
  strict
1353
1305
    Attempting to print an unprintable character will cause a UnicodeError.
1354
1306
    This is for commands that are intended more as scripting support, rather
1358
1310
    printed a filename with a '?', the wrong file could be deleted. (At the
1359
1311
    very least, the correct file would not be deleted). An error is used to
1360
1312
    indicate that the requested action could not be performed.
1361
 
 
 
1313
  
1362
1314
  exact
1363
1315
    Do not attempt to automatically convert Unicode strings. This is used
1364
1316
    for commands that must handle conversion themselves.
1412
1364
 
1413
1365
To create an extension, add rules to setup.py for building it with pyrex,
1414
1366
and with distutils. Now start with an empty .pyx file. At the top add
1415
 
"include 'yourmodule.py'". This will import the contents of foo.py into this
 
1367
"include 'yourmodule.py'". This will import the contents of foo.py into this 
1416
1368
file at build time - remember that only one module will be loaded at
1417
1369
runtime. Now you can subclass classes, or replace functions, and only your
1418
1370
changes need to be present in the .pyx file.
1419
1371
 
1420
1372
Note that pyrex does not support all 2.4 programming idioms, so some
1421
 
syntax changes may be required. I.e.
 
1373
syntax changes may be required. I.e. 
1422
1374
 
1423
 
 - 'from foo import (bar, gam)' needs to change to not use the brackets.
1424
 
 - 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar'
 
1375
 - 'from foo import (bar, gam)' needs to change to not use the brackets. 
 
1376
 - 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar' 
1425
1377
 
1426
1378
If the changes are too dramatic, consider
1427
1379
maintaining the python code twice - once in the .pyx, and once in the .py,
1451
1403
* reviewing changes
1452
1404
* reviewing blueprints
1453
1405
* planning releases
1454
 
* managing releases (see `Releasing Bazaar <http://doc.bazaar-vcs.org/developers/releasing.html>`_)
 
1406
* managing releases (see the `Releasing Bazaar <../../developers/releasing.html>`_)
1455
1407
 
1456
1408
.. note::
1457
1409
  Removing barriers to community participation is a key reason for adopting
1704
1656
.. note::
1705
1657
  As well as prioritizing bugs and nominating them against a
1706
1658
  target milestone, Launchpad lets core developers offer to mentor others in
1707
 
  fixing them.
 
1659
  fixing them. 
1708
1660
 
1709
1661
 
1710
1662
..