~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to HACKING

  • Committer: Martin Pool
  • Date: 2006-01-06 01:13:05 UTC
  • mfrom: (1534.1.4 integration)
  • Revision ID: mbp@sourcefrog.net-20060106011305-3772285d84b5cbb4
[merge] robertc

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
 
 
79
 
 
80
Standard parameter types
 
81
------------------------
 
82
 
 
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.
65
90
 
66
91
Documentation
67
92
=============