Bazaar

Merge lp:~mbp/bzr/doc into lp:bzr

  1. doc
  2. Merge into bzr.dev
Proposed by Martin Pool
Status: Merged
Approved by: John A Meinel
Approved revision: no longer in the source branch.
Merged at revision: not available
Proposed branch: lp:~mbp/bzr/doc
Merge into: lp:bzr
Diff against target: 39 lines
1 file modified
doc/developers/HACKING.txt (+7/-6)
To merge this branch: bzr merge lp:~mbp/bzr/doc
Reviewer Review Type Date Requested Status
John A Meinel Approve
Review via email: mp+12663@code.launchpad.net
To post a comment you must log in.
Revision history for this message
Martin Pool (mbp) wrote :

Updates for the new stable branch policy. See list thread "interface deprecation/removal policy".

Revision history for this message
John A Meinel (jameinel) :
review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'doc/developers/HACKING.txt'
2--- doc/developers/HACKING.txt 2009-09-09 12:57:43 +0000
3+++ doc/developers/HACKING.txt 2009-09-30 15:00:33 +0000
4@@ -620,12 +620,10 @@
5 Naming
6 ======
7
8-Functions, methods or members that are "private" to bzrlib are given
9+Functions, methods or members that are relatively private are given
10 a leading underscore prefix. Names without a leading underscore are
11 public not just across modules but to programmers using bzrlib as an
12-API. As a consequence, a leading underscore is appropriate for names
13-exposed across modules but that are not to be exposed to bzrlib API
14-programmers.
15+API.
16
17 We prefer class names to be concatenated capital words (``TestCase``)
18 and variables, methods and functions to be lowercase words joined by
19@@ -847,8 +845,8 @@
20 Evolving Interfaces
21 ===================
22
23-We have a commitment to 6 months API stability - any supported symbol in a
24-release of bzr MUST NOT be altered in any way that would result in
25+We don't change APIs in stable branches: any supported symbol in a stable
26+release of bzr must not be altered in any way that would result in
27 breaking existing code that uses it. That means that method names,
28 parameter ordering, parameter names, variable and attribute names etc must
29 not be changed without leaving a 'deprecated forwarder' behind. This even
30@@ -860,6 +858,9 @@
31 keyword parameter to branch.commit which is a *required* transaction
32 object, I should rename the API - i.e. to 'branch.commit_transaction'.
33
34+ (Actually, that may break code that provides a new implementation of
35+ ``commit`` and doesn't expect to receive the parameter.)
36+
37 When renaming such supported API's, be sure to leave a deprecated_method (or
38 _function or ...) behind which forwards to the new API. See the
39 bzrlib.symbol_versioning module for decorators that take care of the