← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/HACKING.txt

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2009-10-01 07:23:07 UTC
  • mfrom: (4719.2.1 doc)
  • Revision ID: pqm@pqm.ubuntu.com-20091001072307-u01ny02917u8mmfg
(mbp) updated instructions about api stability

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/HACKING.txt
620
620
Naming
621
621
======
622
622
 
623
 
Functions, methods or members that are "private" to bzrlib are given
 
623
Functions, methods or members that are relatively private are given
624
624
a leading underscore prefix.  Names without a leading underscore are
625
625
public not just across modules but to programmers using bzrlib as an
626
 
API. As a consequence, a leading underscore is appropriate for names
627
 
exposed across modules but that are not to be exposed to bzrlib API
628
 
programmers.
 
626
API. 
629
627
 
630
628
We prefer class names to be concatenated capital words (``TestCase``)
631
629
and variables, methods and functions to be lowercase words joined by
847
845
Evolving Interfaces
848
846
===================
849
847
 
850
 
We have a commitment to 6 months API stability - any supported symbol in a
851
 
release of bzr MUST NOT be altered in any way that would result in
 
848
We don't change APIs in stable branches: any supported symbol in a stable
 
849
release of bzr must not be altered in any way that would result in
852
850
breaking existing code that uses it. That means that method names,
853
851
parameter ordering, parameter names, variable and attribute names etc must
854
852
not be changed without leaving a 'deprecated forwarder' behind. This even
860
858
keyword parameter to branch.commit which is a *required* transaction
861
859
object, I should rename the API - i.e. to 'branch.commit_transaction'. 
862
860
 
 
861
  (Actually, that may break code that provides a new implementation of
 
862
  ``commit`` and doesn't expect to receive the parameter.)
 
863
 
863
864
When renaming such supported API's, be sure to leave a deprecated_method (or
864
865
_function or ...) behind which forwards to the new API. See the
865
866
bzrlib.symbol_versioning module for decorators that take care of the