Rev 3959: (mbp) improved plugin developer documentation in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Mon Jan 26 11:59:32 GMT 2009
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 3959
revision-id: pqm at pqm.ubuntu.com-20090126115928-bzzqlmw316iv8o3k
parent: pqm at pqm.ubuntu.com-20090124185051-8oryvqq68n6repso
parent: mbp at sourcefrog.net-20090124151523-fb5fbarjmbqcygd7
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Mon 2009-01-26 11:59:28 +0000
message:
(mbp) improved plugin developer documentation
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
doc/developers/api-versioning.txt apiversioning.txt-20070626065626-iiihgmhgkv91uphz-1
doc/developers/plugin-api.txt pluginapi.txt-20080229110225-q2j5y4agqhlkjn0s-1
------------------------------------------------------------
revno: 3939.1.9
revision-id: mbp at sourcefrog.net-20090124151523-fb5fbarjmbqcygd7
parent: mbp at sourcefrog.net-20090123223931-kb1la553lxibnbpd
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: doc
timestamp: Sat 2009-01-24 13:15:23 -0200
message:
News entry about plugin docs
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
------------------------------------------------------------
revno: 3939.1.8
revision-id: mbp at sourcefrog.net-20090123223931-kb1la553lxibnbpd
parent: mbp at sourcefrog.net-20090123200435-umq1l6xoepcvgw0c
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: doc
timestamp: Fri 2009-01-23 20:39:31 -0200
message:
Rephrase api docs
modified:
doc/developers/plugin-api.txt pluginapi.txt-20080229110225-q2j5y4agqhlkjn0s-1
------------------------------------------------------------
revno: 3939.1.7
revision-id: mbp at sourcefrog.net-20090123200435-umq1l6xoepcvgw0c
parent: mbp at sourcefrog.net-20090123185245-mjqgjwrw4py3a3kb
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: doc
timestamp: Fri 2009-01-23 18:04:35 -0200
message:
Suggest looking at __name__ in plugins
modified:
doc/developers/plugin-api.txt pluginapi.txt-20080229110225-q2j5y4agqhlkjn0s-1
------------------------------------------------------------
revno: 3939.1.6
revision-id: mbp at sourcefrog.net-20090123185245-mjqgjwrw4py3a3kb
parent: mbp at sourcefrog.net-20090123184533-8p7762lg1jh5cwli
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: doc
timestamp: Fri 2009-01-23 16:52:45 -0200
message:
Correction to how plugins advertise their version
modified:
doc/developers/plugin-api.txt pluginapi.txt-20080229110225-q2j5y4agqhlkjn0s-1
------------------------------------------------------------
revno: 3939.1.5
revision-id: mbp at sourcefrog.net-20090123184533-8p7762lg1jh5cwli
parent: mbp at sourcefrog.net-20090123184410-8no3skbgeghur5jh
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: doc
timestamp: Fri 2009-01-23 16:45:33 -0200
message:
Suggestions how to publish plugins
modified:
doc/developers/plugin-api.txt pluginapi.txt-20080229110225-q2j5y4agqhlkjn0s-1
------------------------------------------------------------
revno: 3939.1.4
revision-id: mbp at sourcefrog.net-20090123184410-8no3skbgeghur5jh
parent: mbp at sourcefrog.net-20090123181344-z40j1j2zjwn4vswy
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: doc
timestamp: Fri 2009-01-23 16:44:10 -0200
message:
More documentation and links about writing plugins
modified:
doc/developers/api-versioning.txt apiversioning.txt-20070626065626-iiihgmhgkv91uphz-1
doc/developers/plugin-api.txt pluginapi.txt-20080229110225-q2j5y4agqhlkjn0s-1
------------------------------------------------------------
revno: 3939.1.3
revision-id: mbp at sourcefrog.net-20090123181344-z40j1j2zjwn4vswy
parent: mbp at sourcefrog.net-20090123175030-etahwt2dg0lqdcel
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: doc
timestamp: Fri 2009-01-23 16:13:44 -0200
message:
More plugin api docs
modified:
doc/developers/plugin-api.txt pluginapi.txt-20080229110225-q2j5y4agqhlkjn0s-1
------------------------------------------------------------
revno: 3939.1.2
revision-id: mbp at sourcefrog.net-20090123175030-etahwt2dg0lqdcel
parent: mbp at sourcefrog.net-20090115075305-lu6m9n2gzl432lh0
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: doc
timestamp: Fri 2009-01-23 15:50:30 -0200
message:
Mention plugin docstrings and give a short example of the api requirement function
modified:
doc/developers/plugin-api.txt pluginapi.txt-20080229110225-q2j5y4agqhlkjn0s-1
=== modified file 'NEWS'
--- a/NEWS 2009-01-24 04:03:08 +0000
+++ b/NEWS 2009-01-26 11:59:28 +0000
@@ -71,6 +71,8 @@
DOCUMENTATION:
+ * Improved plugin developer documentation. (Martin Pool)
+
API CHANGES:
* ``ProgressBarStack`` is deprecated; instead use
=== modified file 'doc/developers/api-versioning.txt'
--- a/doc/developers/api-versioning.txt 2007-06-26 08:27:24 +0000
+++ b/doc/developers/api-versioning.txt 2009-01-23 18:44:10 +0000
@@ -8,7 +8,7 @@
:Date: 2007-06-26
bzrlib has a rich API which is used both internally, and externally by
-plugins and scripts. To allow the API to change, specifically to allow
+plugins_ and scripts. To allow the API to change, specifically to allow
support for features and methods to be removed, without causing hard to
diagnose bugs in the clients of the API, bzrlib provides explicit API
compatibility data, and a compact API to allow scripts and plugins to
@@ -16,6 +16,9 @@
written against.
+.. _plugins: plugin-api.html
+
+
.. contents::
=== modified file 'doc/developers/plugin-api.txt'
--- a/doc/developers/plugin-api.txt 2008-04-06 23:37:06 +0000
+++ b/doc/developers/plugin-api.txt 2009-01-23 22:39:31 +0000
@@ -2,17 +2,29 @@
Plugin API
==========
-Status
-======
-
-:Date: 2008-02-29
+
+
+:Date: 2009-01-23
+
+.. contents::
+
+Introduction
+============
bzrlib has a very flexible internal structure allowing plugins for many
operations. Plugins can add commands, new storage formats, diff and merge
features and more. This document provides an overview of the API and
conventions for plugin authors.
-.. contents::
+If you're writing a plugin and have questions not addressed by this
+document, please ask us.
+
+See also
+--------
+
+ * `Bazaar Developer Documentation Catalog <index.html>`_.
+ * <http://bazaar-vcs.org/WritingPlugins> wiki page with many more
+ suggestions about particular APIs
Structure of a plugin
@@ -157,17 +169,90 @@
Plugin metadata after installation
==================================
-After a plugin has been installed, metadata can be more easily obtained.
-Currently the only metadata used is for API versioning.
+After a plugin has been installed, metadata can be more easily obtained by
+looking inside the module object -- in other words, for variables defined
+in the plugin's ``__init__.py``.
+
+Help and documentation
+----------------------
+
+The module docstring is used as the plugin description shown by ``bzr
+plugins``. As with all Python docstrings, the first line should be a
+short complete sentence summarizing the plugin. The full docstring is
+shown by ``bzr help PLUGIN_NAME``.
+
+Remember that to be effective, the module docstring must be the first
+statement in the file. It may come after comments but it must be before
+any import statements.
API version
-----------
-Please see `API versioning <api-versioning.html>`_ for details on the API
+Plugins can and should declare that they depend on a particular version of
+bzrlib like so::
+
+ from bzrlib.api import require_api
+
+ require_api(bzrlib, (1, 11, 0))
+
+Please see `API versioning <api-versioning.html>`_ for more details on the API
metadata protocol used by bzrlib.
+Plugin version
+--------------
+
+The plugin should expose a version tuple to describe its own version.
+Some plugins use a version number that corresponds to the version of bzr
+they're released against, but you can use whatever you want. For example::
+
+ version_info = (1, 10, 0)
+
+
+Detecting whether code's being loaded as a plugin
+-------------------------------------------------
+
+You may have a Python module that can be used as a bzr plugin and also in
+other places. To detect whether the module is being loaded by bzr, use
+something like this::
+
+ if __name__ == 'bzrlib.plugins.loggerhead':
+ # register with bzrlib...
+
+
+Plugin performance
+==================
+
+Plugins should avoid doing work or loading code from the plugin or
+external libraries, if they're just installed but not actually active,
+because this slows down every invocation of bzr. The bzrlib APIs
+generally allow the plugin to 'lazily' register methods to invoke if a
+particular disk format or seen or a particular command is run.
+
+
+Plugin registrations
+====================
+
+The plugin ``__init__.py`` runs when the plugin is loaded during bzr
+startup. Generally the plugin won't want to actually do anything at this
+time other than register or override functions to be called later.
+
+The plugin can import bzrlib and call any function.
+Some interesting APIs are described in <http://bazaar-vcs.org/WritingPlugins>
+
+
+Publishing your plugin
+======================
+
+When your plugin is basically working you might like to share it with
+other people. Here are some steps to consider:
+
+ * make a project on Launchpad.net like
+ <https://launchpad.net/bzr-fastimport>
+ and publish the branches or tarballs there
+
+ * include the plugin in <http://bazaar-vcs.org/BzrPlugins>
+
+ * post about it to the ``bazaar-announce`` list at ``lists.canonical.com``
..
- vim: ft=rst tw=74 ai
-
-
+ vim: ft=rst tw=74 ai shiftwidth=4
More information about the bazaar-commits
mailing list