← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to HACKING

  • Committer: John Arbash Meinel
  • Date: 2006-10-11 00:23:23 UTC
  • mfrom: (2070 +trunk)
  • mto: This revision was merged to the branch mainline in revision 2071.
  • Revision ID: john@arbash-meinel.com-20061011002323-82ba88c293d7caff
[merge] bzr.dev 2070

Show diffs side-by-side

added added

removed removed

Lines of Context:
HACKING
56
56
applies to modules and classes.
57
57
 
58
58
If you wish to change the behaviour of a supported API in an incompatible
59
 
way, you need to change its name as well. For instance, if I add a optional keyword
 
59
way, you need to change its name as well. For instance, if I add an optional keyword
60
60
parameter to branch.commit - that's fine. On the other hand, if I add a
61
61
keyword parameter to branch.commit which is a *required* transaction
62
62
object, I should rename the API - i.e. to 'branch.commit_transaction'. 
67
67
details for you - such as updating the docstring, and issuing a warning
68
68
when the old api is used.
69
69
 
70
 
For unsupported API's, it does not hurt to follow this discipline, but its
 
70
For unsupported API's, it does not hurt to follow this discipline, but it's
71
71
not required. Minimally though, please try to rename things so that
72
72
callers will at least get an AttributeError rather than weird results.
73
73
 
78
78
There are some common requirements in the library: some parameters need to be
79
79
unicode safe, some need byte strings, and so on. At the moment we have
80
80
only codified one specific pattern: Parameters that need to be unicode
81
 
should be check via 'bzrlib.osutils.safe_unicode'. This will coerce the
 
81
should be checked via 'bzrlib.osutils.safe_unicode'. This will coerce the
82
82
input into unicode in a consistent fashion, allowing trivial strings to be
83
83
used for programmer convenience, but not performing unpredictably in the
84
84
presence of different locales.
241
241
~~~~~~~~~~~~~~~~~~~~~~
242
242
 
243
243
While it is possible for ``lazy_import()`` to import members of a module
244
 
wehn using the ``from module import member`` syntax, it is recommended to
 
244
when using the ``from module import member`` syntax, it is recommended to
245
245
only use that syntax to load sub modules ``from module import submodule``.
246
246
This is because variables and classes can frequently be used without
247
247
needing a sub-member for example::
338
338
    the command. We do this so that the library api has continual pressure
339
339
    on it to be as functional as the command line in a simple manner, and
340
340
    to isolate knock-on effects throughout the blackbox test suite when a
341
 
    command changes it name or signature. Ideally only the tests for a
 
341
    command changes its name or signature. Ideally only the tests for a
342
342
    given command are affected when a given command is changed.
343
343
 
344
344
Doctests
463
463
    that cannot be displayed.
464
464
  
465
465
  strict
466
 
    Attempting to print and unprintable character will cause a UnicodeError.
 
466
    Attempting to print an unprintable character will cause a UnicodeError.
467
467
    This is for commands that are intended more as scripting support, rather
468
468
    than plain user review.
469
469
    For exampl: ``bzr ls`` is designed to be used with shell scripting. One