From: Christopher Allan Webber <cwebber@dustycloud.org>
Date: Fri, 25 Mar 2016 22:47:19 +0000 (-0700)
Subject: doc: Update plugins documentation in light of alembic branching usage
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=cca25b6fcfd47a95bd1cf1b00adf036b2f8f331b;p=mediagoblin.git

doc: Update plugins documentation in light of alembic branching usage

* docs/source/siteadmin/plugins.rst:
  Added a reminder to run "./bin/gmg dbupdate" after installing a plugin.
  Added a new "Deactivating plugins" section.
  Renamed "Removing plugins" to "Removing plugin packages".
---

diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst
index 1f82c670..67c8bad1 100644
--- 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