Rev 4721: (mbp) updated instructions about api stability in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

Canonical.com Patch Queue Manager pqm at pqm.ubuntu.com
Thu Oct 1 08:23:09 BST 2009


At file:///home/pqm/archives/thelove/bzr/%2Btrunk/

------------------------------------------------------------
revno: 4721 [merge]
revision-id: pqm at pqm.ubuntu.com-20091001072307-u01ny02917u8mmfg
parent: pqm at pqm.ubuntu.com-20091001033348-gozepgwz0kiyj28u
parent: mbp at sourcefrog.net-20090930145621-q92ub6xacunb0q8a
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Thu 2009-10-01 08:23:07 +0100
message:
  (mbp) updated instructions about api stability
modified:
  doc/developers/HACKING.txt     HACKING-20050805200004-2a5dc975d870f78c
=== modified file 'doc/developers/HACKING.txt'
--- a/doc/developers/HACKING.txt	2009-09-09 12:57:43 +0000
+++ b/doc/developers/HACKING.txt	2009-09-30 14:56:21 +0000
@@ -620,12 +620,10 @@
 Naming
 ======
 
-Functions, methods or members that are "private" to bzrlib are given
+Functions, methods or members that are relatively private are given
 a leading underscore prefix.  Names without a leading underscore are
 public not just across modules but to programmers using bzrlib as an
-API. As a consequence, a leading underscore is appropriate for names
-exposed across modules but that are not to be exposed to bzrlib API
-programmers.
+API. 
 
 We prefer class names to be concatenated capital words (``TestCase``)
 and variables, methods and functions to be lowercase words joined by
@@ -847,8 +845,8 @@
 Evolving Interfaces
 ===================
 
-We have a commitment to 6 months API stability - any supported symbol in a
-release of bzr MUST NOT be altered in any way that would result in
+We don't change APIs in stable branches: any supported symbol in a stable
+release of bzr must not be altered in any way that would result in
 breaking existing code that uses it. That means that method names,
 parameter ordering, parameter names, variable and attribute names etc must
 not be changed without leaving a 'deprecated forwarder' behind. This even
@@ -860,6 +858,9 @@
 keyword parameter to branch.commit which is a *required* transaction
 object, I should rename the API - i.e. to 'branch.commit_transaction'. 
 
+  (Actually, that may break code that provides a new implementation of
+  ``commit`` and doesn't expect to receive the parameter.)
+
 When renaming such supported API's, be sure to leave a deprecated_method (or
 _function or ...) behind which forwards to the new API. See the
 bzrlib.symbol_versioning module for decorators that take care of the




More information about the bazaar-commits mailing list