← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to HACKING

  • Committer: Robert Collins
  • Date: 2005-10-17 11:56:54 UTC
  • mfrom: (1185.16.59)
  • Revision ID: robertc@robertcollins.net-20051017115654-662239e1587524a8
merge from martin.

Show diffs side-by-side

added added

removed removed

Lines of Context:
HACKING
21
21
  core improvements should be tested closer to the code that is doing the
22
22
  work. Command line level tests should be placed in 'blackbox.py'.
23
23
 
24
 
* Try to practice Test-Driven Development.  before fixing a bug, write a
25
 
  test case so that it does not regress.  Similarly for adding a new
26
 
  feature: write a test case for a small version of the new feature before
27
 
  starting on the code itself.  Check the test fails on the old code, then
28
 
  add the feature or fix and check it passes.
 
24
* Before fixing a bug, write a test case so that it does not regress.
29
25
 
30
26
* Exceptions should be defined inside bzrlib.errors, so that we can
31
27
  see the whole tree at a glance.
38
34
* Module names should always be given fully-qualified,
39
35
  i.e. ``bzrlib.hashcache`` not just ``hashcache``.
40
36
 
41
 
* Commands should return non-zero when they encounter circumstances that
42
 
  the user should really pay attention to - which includes trivial shell
43
 
  pipelines.
44
 
 
45
 
  Recommended values are 
46
 
    0- OK, 
47
 
    1- Conflicts in merge-like operations, or changes are present in
48
 
       diff-like operations. 
49
 
    2- Unrepresentable diff changes (i.e. binary files that we cannot show 
50
 
       a diff of).
51
 
    3- An error or exception has occurred.
52
 
 
53
37
Evolving interfaces
54
38
-------------------
55
39
 
57
41
be sure to change its name as well. For instance, if I add a keyword
58
42
parameter to branch.commit - that's fine. On the other hand, if I add
59
43
a keyword parameter to branch.commit which is a *required* transaction
60
 
object, I should rename the API - i.e. to 'branch.commit_transaction'.
 
44
object, I should rename the api - i.e. to 'branch.commit_transaction'.
61
45
 
62
 
This will prevent users of the old API getting surprising results. 
63
 
Instead, they will get an Attribute error as the API is missing, and
 
46
This will prevent users of the old api getting surprising results. 
 
47
Instead, they will get an Attribute error as the api is missing, and
64
48
will know to update their code. If in doubt, just ask on #bzr.
65
49
 
66
50
Documentation
69
53
If you change the behaviour of a command, please update its docstring
70
54
in bzrlib/commands.py.  This is displayed by the 'bzr help' command.
71
55
 
72
 
NEWS file
73
 
---------
74
 
 
75
56
If you make a user-visible change, please add a note to the NEWS file.
76
57
The description should be written to make sense to someone who's just
77
58
a user of bzr, not a developer: new functions or classes shouldn't be
79
60
bugs should be listed.  See the existing entries for an idea of what
80
61
should be done.
81
62
 
82
 
Within each release, entries in the news file should have the most
83
 
user-visible changes first.  So the order should be approximately:
84
 
 
85
 
 * changes to existing behaviour - the highest priority because the 
86
 
   user's existing knowledge is incorrect
87
 
 * new features - should be brought to their attention
88
 
 * bug fixes - may be of interest if the bug was affecting them, and
89
 
   should include the bug number if any
90
 
 * major documentation changes
91
 
 * changes to internal interfaces
92
 
 
93
 
People who made significant contributions to each change are listed in
94
 
parenthesis.  This can include reporting bugs (particularly with good
95
 
details or reproduction recipes), submitting patches, etc.
96
63
 
97
64
API documentation
98
65
-----------------
152
119
(not ``x2y`` as occurs in some old code.)
153
120
 
154
121
 
155
 
Destructors
156
 
-----------
157
 
 
158
 
Python destructors (``__del__``) work differently to those of other
159
 
languages.  In particular, bear in mind that destructors may be called
160
 
immediately when the object apparently becomes unreferenced, or at some
161
 
later time, or possibly never at all.  Therefore we have restrictions on
162
 
what can be done inside them.
163
 
 
164
 
 0. Never use a __del__ method without asking Martin/Robert first.
165
 
 
166
 
 1. Never rely on a ``__del__`` method running.  If there is code that
167
 
    must run, do it from a ``finally`` block instead.
168
 
 
169
 
 2. Never ``import`` from inside a ``__del__`` method, or you may crash the
170
 
    interpreter!!
171
 
 
172
 
 3. In some places we raise a warning from the destructor if the object
173
 
    has not been cleaned up or closed.  This is considered OK: the warning
174
 
    may not catch every case but it's still useful sometimes.
175
 
 
176
 
 
177
122
Writing output
178
123
==============
179
124
 
233
178
Errors and exceptions
234
179
=====================
235
180
 
236
 
Errors are handled through Python exceptions.  They can represent user
237
 
errors, environmental errors or program bugs.  Sometimes we can't be sure
238
 
at the time it's raised which case applies.  See bzrlib/errors.py for 
239
 
details on the error-handling practices.
 
181
[write me]
240
182
 
241
183
 
242
184
Jargon
246
188
    Integer identifier for a revision on the main line of a branch.
247
189
    Revision 0 is always the null revision; others are 1-based
248
190
    indexes into the branch's revision history.
249
 
 
250
 
:: vim: tw=74 ai