/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/developers/api-versioning.txt

  • Committer: Robert Collins
  • Date: 2007-06-26 06:57:20 UTC
  • mto: This revision was merged to the branch mainline in revision 2554.
  • Revision ID: robertc@robertcollins.net-20070626065720-w0btzadye6lpq104
API Versioning proposal document.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/api-versioning.txt
8
8
:Date: 2007-06-26
9
9
 
10
10
bzrlib has a rich API which is used both internally, and externally by
11
 
plugins_ and scripts. To allow the API to change, specifically to allow
 
11
plugins and scripts. To allow the API to change, specifically to allow
12
12
support for features and methods to be removed, without causing hard to
13
13
diagnose bugs in the clients of the API, bzrlib provides explicit API
14
14
compatibility data, and a compact API to allow scripts and plugins to
16
16
written against.
17
17
 
18
18
 
19
 
.. _plugins: plugin-api.html
20
 
 
21
 
 
22
19
.. contents::
23
20
 
24
21
 
50
47
express, and easier for a human to look at and understand, and finally
51
48
easier to manage. The oldest version with which the API for a python
52
49
object is compatible is obtained by looking up the ``api_minimum_version``
53
 
attribute on the python object handed to ``require_api``, and failing that
54
 
the bzrlib ``api_minimum_version`` is returned. The current version of the
55
 
API is obtained by looking for an ``api_current_version`` attribute, and
56
 
if that is not found, an ``version_info`` attribute (of which the first 3
57
 
elements are used). If no current version can be found, the bzrlib
58
 
``version_info`` attribute is used to generate a current API version.
59
 
This lookup sequence allows users with simple setups (and no python style
60
 
``version_info`` tuple) to still export an API version, and for new API's
61
 
to be managed more granularly later on with a smooth transition -
62
 
everything starts off in lockstep with bzrlib's master version.
63
 
 
64
 
API versions are compared lexically to answer the question 'is
 
50
attribute on the python object handed to ``require_api``. The current
 
51
version of the API is obtained by looking for an ``api_current_version``
 
52
attribute, and if that is not found, an ``version_info`` attribute (of
 
53
which the first 3 elements are used). If no current version can be found,
 
54
the bzrlib ``version_info`` attribute is used to generate a current API
 
55
version. API versions are compared lexically to answer the question 'is
65
56
the requested version X <= the current version, and >= the minimum
66
57
version'.
67
58
 
86
77
with ``(0, 18, 0)``.
87
78
 
88
79
+------------+---------------+
89
 
| API        | Covers        |
90
 
+============+===============+
 
80
| API        | Covers        | 
 
81
+============+===============+ 
91
82
| bzrlib     | All of bzrlib |
92
83
+------------+---------------+
93
84