← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to HACKING

Exclude more files from dumb-rsync upload

Show diffs side-by-side

added added

removed removed

Lines of Context:
HACKING
34
34
* Module names should always be given fully-qualified,
35
35
  i.e. ``bzrlib.hashcache`` not just ``hashcache``.
36
36
 
 
37
* Commands should return Non-Zero when they encounter circumstances that
 
38
  the user should really pay attention to - which includes trivial shell
 
39
  pipelines.
 
40
 
 
41
  Recommended values are 
 
42
    0- OK, 
 
43
    1- Conflicts in merge-like operations, or changes are present in
 
44
       diff-like operations. 
 
45
    2- Unrepresentable diff changes (i.e. binary files that we cannot show 
 
46
       a diff of).
 
47
    3- An error or exception has occurred.
 
48
 
37
49
Evolving interfaces
38
50
-------------------
39
51
 
41
53
be sure to change its name as well. For instance, if I add a keyword
42
54
parameter to branch.commit - that's fine. On the other hand, if I add
43
55
a keyword parameter to branch.commit which is a *required* transaction
44
 
object, I should rename the api - i.e. to 'branch.commit_transaction'.
 
56
object, I should rename the API - i.e. to 'branch.commit_transaction'.
45
57
 
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
 
58
This will prevent users of the old API getting surprising results. 
 
59
Instead, they will get an Attribute error as the API is missing, and
48
60
will know to update their code. If in doubt, just ask on #bzr.
49
61
 
50
62
Documentation
53
65
If you change the behaviour of a command, please update its docstring
54
66
in bzrlib/commands.py.  This is displayed by the 'bzr help' command.
55
67
 
 
68
NEWS file
 
69
---------
 
70
 
56
71
If you make a user-visible change, please add a note to the NEWS file.
57
72
The description should be written to make sense to someone who's just
58
73
a user of bzr, not a developer: new functions or classes shouldn't be
60
75
bugs should be listed.  See the existing entries for an idea of what
61
76
should be done.
62
77
 
 
78
Within each release, entries in the news file should have the most
 
79
user-visible changes first.  So the order should be approximately:
 
80
 
 
81
 * changes to existing behaviour - the highest priority because the 
 
82
   user's existing knowledge is incorrect
 
83
 * new features - should be brought to their attention
 
84
 * bug fixes - may be of interest if the bug was affecting them, and
 
85
   should include the bug number if any
 
86
 * major documentation changes
 
87
 * changes to internal interfaces
 
88
 
 
89
People who made significant contributions to each change are listed in
 
90
parenthesis.  This can include reporting bugs (particularly with good
 
91
details or reproduction recipes), submitting patches, etc.
63
92
 
64
93
API documentation
65
94
-----------------
119
148
(not ``x2y`` as occurs in some old code.)
120
149
 
121
150
 
 
151
Destructors
 
152
-----------
 
153
 
 
154
Python destructors (``__del__``) work differently to those of other
 
155
languages.  In particular, bear in mind that destructors may be called
 
156
immediately when the object apparently becomes unreferenced, or at some
 
157
later time, or possibly never at all.  Therefore we have restrictions on
 
158
what can be done inside them.
 
159
 
 
160
 0. Never use a __del__ method without asking Martin/Robert first.
 
161
 
 
162
 1. Never rely on a ``__del__`` method running.  If there is code that
 
163
    must run, do it from a ``finally`` block instead.
 
164
 
 
165
 2. Never ``import`` from inside a ``__del__`` method, or you may crash the
 
166
    interpreter!!
 
167
 
 
168
 3. In some places we raise a warning from the destructor if the object
 
169
    has not been cleaned up or closed.  This is considered OK: the warning
 
170
    may not catch every case but it's still useful sometimes.
 
171
 
 
172
 
122
173
Writing output
123
174
==============
124
175
 
191
242
    Integer identifier for a revision on the main line of a branch.
192
243
    Revision 0 is always the null revision; others are 1-based
193
244
    indexes into the branch's revision history.
 
245
 
 
246
:: vim: tw=74 ai