← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to HACKING

 * Deprecated functions and methods can now be marked as such using the 
   bzrlib.symbol_versioning module. Marked method have their docstring
   updated and will issue a DeprecationWarning using the warnings module
   when they are used. (Robert Collins)

Show diffs side-by-side

added added

removed removed

Lines of Context:
HACKING
53
53
Evolving interfaces
54
54
-------------------
55
55
 
56
 
If you change the behaviour of an API in an incompatible way, please
57
 
be sure to change its name as well. For instance, if I add a keyword
58
 
parameter to branch.commit - that's fine. On the other hand, if I add
59
 
a keyword parameter to branch.commit which is a *required* transaction
60
 
object, I should rename the API - i.e. to 'branch.commit_transaction'.
61
 
 
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
64
 
will know to update their code. If in doubt, just ask on #bzr.
 
56
We have a commitment to 6 months API stability - any supported symbol in a
 
57
release of bzr MUST NOT be altered in any way that would result in
 
58
breaking existing code that uses it. That means that method names,
 
59
parameter ordering, parameter names, variable and attribute names etc must
 
60
not be changed without leaving a 'deprecated forwarder' behind. This even
 
61
applies to modules and classes.
 
62
 
 
63
If you wish to change the behaviour of a supported API in an incompatible
 
64
way, you need to change its name as well. For instance, if I add a optional keyword
 
65
parameter to branch.commit - that's fine. On the other hand, if I add a
 
66
keyword parameter to branch.commit which is a *required* transaction
 
67
object, I should rename the API - i.e. to 'branch.commit_transaction'. 
 
68
 
 
69
When renaming such supported API's, be sure to leave a deprecated_method (or
 
70
_function or ...) behind which forwards to the new API. See the
 
71
bzrlib.symbol_versioning module for decorators that take care of the
 
72
details for you - such as updating the docstring, and issuing a warning
 
73
when the old api is used.
 
74
 
 
75
For unsupported API's, it does not hurt to follow this discipline, but its
 
76
not required. Minimally though, please try to rename things so that
 
77
callers will at least get an AttributeError rather than weird results.
 
78
 
65
79
 
66
80
Documentation
67
81
=============