[MERGE] Add a plugin-api.txt developer document starting to description services for/from plugins.

[Robert Collins]

On Fri, 2008-02-29 at 07:27 -0500, Martin Pool wrote:
> Martin Pool has voted resubmit.

Thanks for the review... at the end of this mail is an incremental diff.

> Status is now: Resubmit
> Comment:
> > +==========
> > +Plugin API
> > +==========
> > +
> > +Status
> > +======
> > +
> > +:Date: 2008-02-29
> > +
>  > +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.
> > +
> 
> The "Status" heading is strange (orphaned?), so I suggest you just
> remove it and put this text as introductory matter before the contents.
> Also, delete the "motivation" section and just add
> 
>    This document provides an overview of the API and conventions for 
> plugin authors.
> 
> Please delete the date; this always either goes out of date or causes
> confusion about whether it should be updated by minor changes.

I've replaced the motivation section as you request, however I would
much rather be consistent with other docs than change layout style
again.


> > +
> > +
> > +Plugin metadata before installation
> > +===================================
...
> This needs an earlier section to establish context.

Thanks added.

..
>    As for other Python modules, the name of the directory must match the
>    expected name of the plugin.
> 
> I guess they normally do have a setup.py, though it's unclear to me that
> will interact well with people just putting a checkout under
> ~/.bazaar/plugins.

Seems to work fine to me :).

> > +
> > +Design


> Delete heading, rephrase to

Done.


> > +
> > +Metadata protocol
> > +-----------------
> > +
> > +A plugin that supports the bzr plugin metadata protocol will do two
>  > +things. Firstly, the ``setup.py`` for the plugin will guard the call 
> to
> > +``setup()``::
> > +
> > +  if __name__ == 'main':
> > +      setup(...)
> > +
>  > +Secondly, the setup module will have one or more of the following 
> variables
>  > +present at module scope. Any variables that are missing will be given 
> the
>  > +defaults from the table. An example of every variable is provided 
> after
> > +the full list.
> 
> It seems like we are basically overriding setup.py here.  Why not have a
> separate file, say bzr_plugin_meta.py, with these variables.  It can
> then be loaded from setup.py if desired.
> 
> After all it is quite possible that loading setup.py may have side
> effects or raise errors.

Well, so could loading bzr_plugin_meta. It's very common to use the
versions we're exposing through this api in setup.py, I think forcing a
separate file will just be inconvenient for people.

> > +
>  > 
> ++------------------------+---------+----------------------------------------+
>  > +| Variable               | Default | Definition 
> |
>  > 
> ++========================+=========+========================================+
>  > +| bzr_plugin_name        | None    | The name the plugin package 
> should be  |
>  > +|                        |         | given on disk. The plugin is 
> then      |
>  > +|                        |         | available to python at 
> |
>  > +|                        |         | bzrlib.plugins.NAME 
> |
>  > 
> ++------------------------+---------+----------------------------------------+
>  > +| bzr_commands           | []      | A list of the commands that the 
> plugin |
>  > +|                        |         | provides. Commands that already 
> exist  |
>  > +|                        |         | in bzr and are decorated by the 
> plugin |
>  > +|                        |         | do not need to be listed (but it 
> is not|
>  > +|                        |         | harmful if you do list them). 
> |
> 
> Probably we should list the commands that are overridden.

I think that that is often going to be noise; if you feel strongly I'll
change this. Remember this is for allowing prediction of what plugin to
install to get a feature, knowing that 'status' is overriden isn't going
to help with that much.

>  > 
> ++------------------------+---------+----------------------------------------+
>  > +| bzr_plugin_version     | None    | A version_info 5-tuple with the 
> plugins|
>  > +|                        |         | version. 
> |
> 
>    plugin's
> 
> and give an example (1, 1, 0, 'final', 0)

There are comprehensive examples at the end.The table text is already
dense enough I feel.


>  > +| bzr_repository_formats | {} As bzr_checkout_formats but for 
> repositories. |
>  > 
> ++------------------------+---------+----------------------------------------+
> 
> Broken ReST here.

How so? make docs is not complaining...

-Rob
=== modified file 'doc/developers/plugin-api.txt'
--- doc/developers/plugin-api.txt	2008-02-29 11:09:08 +0000
+++ doc/developers/plugin-api.txt	2008-04-04 04:38:23 +0000
@@ -9,16 +9,22 @@
 
 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.
-
+features and more. This document provides an overview of the API and
+conventions for plugin authors.
 
 .. contents::
 
 
-Motivation
-==========
-
-To provide a pithy central document for plugin authors to refer to.
+Structure of a plugin
+=====================
+
+Plugins are Python modules under ``bzrlib.plugins``. They can be installed
+either into the PYTHONPATH in that location, or in ~/.bazaar/plugins.
+
+Plugins should have a setup.py.
+
+As for other Python modules, the name of the directory must match the
+expected name of the plugin.
 
 
 Plugin metadata before installation
@@ -29,14 +35,11 @@
 such as to generate a directory of plugins, or install them via a
 symlink/checkout to ~/.bazaar/plugins.
 
-Design
-------
+This interface allows bzr to interrogate a plugin without actually loading
+it. This is useful because loading a plugin may have side effects such
+as registering or overriding commands, or the plugin may raise an error,
+if for example a prerequisite is not present.
 
-Because loading a plugin is all that is required to activate it, and
-because plugins may require external dependencies to load properly (such
-as being specific to the Windows platform), we use a separate interface to
-obtain plugin metadata from the setup.py script which plugins will
-typically have.
 
 Metadata protocol
 -----------------
@@ -97,7 +100,7 @@
 ---------------
 
 Because disk format detection for formats that bzr does not understand at
-all can be useful, we allow a declaritive description of the shape of a
+all can be useful, we allow a declarative description of the shape of a
 control directory. Each description has a name for showing to users, and a
 dictonary of relative paths, and the content needed at each path. Paths
 that end in '/' are required to be directories and the value for that key

-- 
GPG key available at: <http://www.robertcollins.net/keys.txt>.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20080404/f2b2a6de/attachment-0001.pgp