From e1325ed4d6c9e53a636d9a4fd906a6d95eefea88 Mon Sep 17 00:00:00 2001
From: Matt Westcott <matt@west.co.tt>
Date: Thu, 25 Jan 2018 16:38:38 +0000
Subject: [PATCH] Release notes and documentation for Draftail (#4136)

---
 CHANGELOG.txt                                 |  1 +
 .../customisation/page_editing_interface.rst  | 12 ++++++++++
 docs/releases/2.0.rst                         | 22 +++++++++++++++++++
 3 files changed, 35 insertions(+)

diff --git a/CHANGELOG.txt b/CHANGELOG.txt
index 01522aef15..a5927d9779 100644
--- a/CHANGELOG.txt
+++ b/CHANGELOG.txt
@@ -6,6 +6,7 @@ Changelog
 
  * Added support for Django 2.0 (Matt Westcott, Karl Hobley, LB (Ben Johnston), Mads Jensen)
  * Reorganised module paths (Karl Hobley, Matt Westcott)
+ * Replaced the hallo.js rich text editor with Draftail (Thibaud Colas, Loïc Teixeira, Matt Westcott)
  * Removed support for Python 2.7, Django 1.8 and Django 1.10
  * Removed support for Elasticsearch 1.x
  * Added the ability to schedule updates to existing published pages (Patrick Woods)
diff --git a/docs/advanced_topics/customisation/page_editing_interface.rst b/docs/advanced_topics/customisation/page_editing_interface.rst
index 2001b01f6a..1f1729612d 100644
--- a/docs/advanced_topics/customisation/page_editing_interface.rst
+++ b/docs/advanced_topics/customisation/page_editing_interface.rst
@@ -101,6 +101,18 @@ This process for adding new features is described in the following sections.
 Extending the WYSIWYG Editor (``hallo.js``)
 +++++++++++++++++++++++++++++++++++++++++++
 
+.. note::
+  The customisations described here are only available on the hallo.js rich text editor used on Wagtail 1.x. To use hallo.js on Wagtail 2.x, add the following to your settings:
+
+  .. code-block:: python
+
+    WAGTAILADMIN_RICH_TEXT_EDITORS = {
+        'default': {
+            'WIDGET': 'wagtail.admin.rich_text.HalloRichTextArea'
+        }
+    }
+
+
 Wagtail's rich text editor is built on ``hallo.js``, and its functionality can be extended through plugins. For information on developing custom ``hallo.js`` plugins, see the project's page: https://github.com/bergie/hallo
 
 Once the plugin has been created, it should be registered through the feature registry's ``register_editor_plugin(editor, feature_name, plugin)`` method. For a ``hallo.js`` plugin, the ``editor`` parameter should always be ``'hallo'``.
diff --git a/docs/releases/2.0.rst b/docs/releases/2.0.rst
index 5f9729cdc4..174f19ff39 100644
--- a/docs/releases/2.0.rst
+++ b/docs/releases/2.0.rst
@@ -16,6 +16,12 @@ Added Django 2.0 support
 Wagtail is now compatible with Django 2.0. Compatibility fixes were contributed by Matt Westcott, Karl Hobley, LB (Ben Johnston) and Mads Jensen.
 
 
+New rich text editor
+~~~~~~~~~~~~~~~~~~~~
+
+Wagtail's rich text editor has now been replaced with `Draftail <https://github.com/springload/draftail>`_, a new editor based on `Draft.js <https://draftjs.org/>`_, fixing numerous bugs and providing an improved editing experience, better support for current browsers, and more consistent HTML output. This feature was developed by Thibaud Colas, Loïc Teixeira and Matt Westcott.
+
+
 Reorganised modules
 ~~~~~~~~~~~~~~~~~~~
 
@@ -173,6 +179,20 @@ However, note that this only applies to dotted module paths beginning with ``wag
 * Template tag library names, e.g. ``{% load wagtailcore_tags %}``
 
 
+Hallo.js customisations are unavailable on the Draftail rich text editor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Draftail rich text editor has a substantially different API from Hallo.js, including the use of a non-HTML format for its internal data representation; as a result, functionality added through Hallo.js plugins will be unavailable. If your project is dependent on Hallo.js-specific behaviour, you can revert to the original Hallo-based editor by adding the following to your settings:
+
+  .. code-block:: python
+
+    WAGTAILADMIN_RICH_TEXT_EDITORS = {
+        'default': {
+            'WIDGET': 'wagtail.admin.rich_text.HalloRichTextArea'
+        }
+    }
+
+
 Removed support for Elasticsearch 1.x
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -230,6 +250,8 @@ can be rewritten as:
         # add 'blockquote' to the default feature set
         features.default_features.append('blockquote')
 
+Please note that the new Draftail rich text editor uses a different mechanism to process rich text content, and does not apply whitelist rules; they only take effect when the Hallo.js editor is in use.
+
 
 ``wagtail.images.views.serve.generate_signature`` now returns a string
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~