doc: Update plugins documentation in light of alembic branching usage

[mediagoblin.git] / docs / source / siteadmin / plugins.rst

diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst
index 1f82c670238f3f62e5b2a3912a6cb6f3bb5d91e0..67c8bad10befff53cb2be88c5ad1ce5a639257c3 100644 (file)
--- a/docs/source/siteadmin/plugins.rst
+++ b/docs/source/siteadmin/plugins.rst
@@ -110,11 +110,32 @@ comments making the bits clearer)::
 Check the plugin's documentation for what configuration options are
 available.
 
+Once you've set up your plugin, you should be sure to update the
+database to accomodate the new plugins::
 
-Removing plugins
-================
+  ./bin/gmg dbupdate
 
-To remove a plugin, use ``pip uninstall``. For example::
+
+Deactivating plugins
+====================
+
+You should be aware that once you enable a plugin, deactivating it
+might be a bit tricky, for migrations reasons.  In the future we may
+produce better tooling to accomodate this.  In short, you will need to
+do a bit of database surgery by:
+
+- Removing all tables and indexes installed by the plugin
+- Removing the plugin's migration head id from the `alembic_version`
+  table.  (You might be able to determine which to remove via
+  examining the output of `./bin/gmg alembic heads`)
+
+Note that this is a VERY TRICKY process, and you should be sure to make
+a backup first.  You've been warned!
+
+Removing plugin packages
+========================
+
+To remove an external plugin's package, use ``pip uninstall``. For example::
 
     pip uninstall mediagoblin-licenses