PluginSystemDesignDocument

Status
February 25th, 2012: Initial writing. Needs work.

Discussion on this document happens on IRC in #mediagoblin, on the dev mailing list and on the discussion page.

Covered in

Use cases
This is a set of use cases we're thinking about. It is not exhaustive.


 * site flat pages (about this site, donations page, how to contribute, how to get an account, terms of service, ...)
 * add restrictions to uploaded content
 * restrict by file size
 * restrict by type
 * restrict by dimensions (height x width)
 * quotas (user can only have x images on site, user can only use total of 50mb, ...)
 * comment spam detection
 * authentication
 * additional admin web pages
 * extending existing media types (Add new formats for video encoding or flash display, etc?)
 * things MediaGoblin already kind of does
 * Storage system extensibility
 * Media type extensibility

What makes a good plugin system?

 * 1) plugin management system - The following should be optimized for ease-of-use:
 * 2) * installing plugins
 * 3) * configuring plugins
 * 4) * removing plugins
 * 5) * getting status on plugins
 * 6) * getting errors from plugins
 * 7) plugin API - In order to augment MediaGoblin's behavior, the plugin needs to be able to assert itself into MediaGoblin's various pipelines. This can be done with hook, signals, registration, ...
 * 8) documentation - how to build, test, install, uninstall, and share plugins
 * 9) a place where site admin can find and download plugins

High-level plan
I think the plan should be something along these lines:


 * 1) Install and uninstall the plugin with pip. Then site admins add the plugin to the INSTALLED_APPS configuration. This way it's easy to put the plugin in and out, install, uninstall, etc. Plugins will have additional configuration/setup steps that will be plugin specific such as running  for setting up db tables.
 * 2) Expose our testing framework. Plugins should be testable and it'd be nice to test everything in a GMG install with a single.
 * 3) Expose routing to applications. Maybe even make routing part of the configuration and allow the site admin to specify "mount points" for the various applications. MediaGoblin could either query the application for routes or just pass anything pointed towards a specific mount point to the application and let it deal with routing. I think I prefer the former.
 * 4) Database storage. Migrations, adding new tables.
 * 5) Templates. Adding new templates, template blocks, ...
 * 6) Version checking: plugins should be able to check the gmg version and throw an exception if the plugin doesn't work with that gmg version.
 * 7) Serve static files. Additional CSS, JS, images, ... Symlinks? Static assets directory that gets copied over? Should be an extensions_static directory or etc of both url and filesystem paths, some command like  or something less crappy that gets filled based on config file settings
 * 8) Need to be able to do three different things:
 * 9) * notification: plugin gets notified of some happenstance (maybe like Django signals). Examples: post_save, post_update, ...
 * 10) * transform: plugin gets to modify some thing as it's getting processed. Examples: context processors, adding additional template tags, ...
 * 11) * handler: plugin handles some thing and if the plugin handles it, then processing ends. Examples: authentication, ...
 * 12) Implement a MediaGoblin plugin API. Expose things that need exposing, implement stuff in the core, ...
 * 13) We can do a PyPI-like thing for plugins. Needs to allow for comments, ratings, blah blah blah.
 * 14) Build a plugin writers documentation guide.
 * 15) GMG would/could come with a set of core plugins.

Install/uninstall
TBD.

Routing
TBD.

Database storage
TBD.

Templates
TBD.

Version checking
TBD.

Notification, transform and handler
TBD.

Execution on the plan

 * 1) Flesh out the plan into a better design document and get a consensus on it.
 * 2) Flesh out the design details.
 * 3) Implement initial bits and write documentation.
 * 4) Write some plugins.
 * 5) Iterate going forward: Take stock of where we're at and what we're missing, implement a new piece, ...