53
53
Evolving interfaces
54
54
-------------------
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'.
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.
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'.
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.
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.
80
Standard parameter types
81
------------------------
83
There are some common requirements in the library: some parameters need to be
84
unicode safe, some need byte strings, and so on. At the moment we have
85
only codified one specific pattern: Parameters that need to be unicode
86
should be check via 'bzrlib.osutils.safe_unicode'. This will coerce the
87
input into unicode in a consistent fashion, allowing trivial strings to be
88
used for programmer convenience, but not performing unpredictably in the
89
presence of different locales.
added
removed
HACKING
