Warn that register_facet_classes may change, refs #830

Also documented policy that plugin hooks should not be shipped without a real example. Refs #818
simonw · Jun 10, 2020 · 9f236c4 · 9f236c4
1 parent 57e812d
commit 9f236c4
Show file tree

Hide file tree

Showing 2 changed files with 4 additions and 0 deletions.
diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -12,6 +12,7 @@ General guidelines
 
 * **master should always be releasable**. Incomplete features should live in branches. This ensures that any small bug fixes can be quickly released.
 * **The ideal commit** should bundle together the implementation, unit tests and associated documentation updates. The commit message should link to an associated issue.
+* **New plugin hooks** should only be shipped if accompanied by a separate release of a non-demo plugin that uses them.
 
 .. _devenvironment:
 

diff --git a/docs/plugins.rst b/docs/plugins.rst
@@ -891,6 +891,9 @@ register_facet_classes()
 
 Return a list of additional Facet subclasses to be registered.
 
+.. warning::
+    The design of this plugin hook is unstable and may change. See `issue 830 <https://github.com/simonw/datasette/issues/830>`__.
+
 Each Facet subclass implements a new type of facet operation. The class should look like this:
 
 .. code-block:: python