Status section in docs

README.rst

@@ -97,6 +97,52 @@ Documentation
 The documentation for how to use django-ftl is in the docs/folder and online at
 https://django-ftl.readthedocs.io.
 
+Status
+------
+
+This package should be considered a beta. While it has a good feature set, test
+suite and docs, it has not been used a huge amount in production. In addition,
+it currently relies on `our fork <https://github.com/django-ftl/python-fluent>`_
+of `python-fluent <https://github.com/projectfluent/python-fluent>`_, which has
+the following significant features/changes not yet merged to the official
+version:
+
+* Refined error handling for functions (see `PR
+  <https://github.com/projectfluent/python-fluent/pull/92>`_).
+
+* Compiler implementation (see `compiler branch
+  <https://github.com/django-ftl/python-fluent/tree/compiler_implementation>`_).
+  This is an additional and much faster implementation of ``FluentBundle`` that
+  compiles FTL messages to Python `AST
+  <https://docs.python.org/3/library/ast.html>`_, running the result through
+  `compile
+  <https://docs.python.org/3/library/functions.html?highlight=compile#compile>`_
+  and `exec
+  <https://docs.python.org/3/library/functions.html?highlight=compile#exec>`_.
+
+  Use of ``exec`` for high performance Python code is an established technique
+  used by other projects (e.g. `Jinja2 <http://jinja.pocoo.org/>`_ and `Mako
+  <https://www.makotemplates.org/>`_), and we only use exec on data derived from
+  FTL files, which will normally be created by translators and not potential
+  attackers. Nevertheless there are understandably some security concerns. Using
+  AST objects rather than strings for creating Python code dynamically makes our
+  use of ``exec`` intrinsically safer than some of these other projects, and we
+  also use some `defence-in-depth techniques
+  <https://github.com/django-ftl/python-fluent/blob/compiler_implementation/fluent.runtime/fluent/runtime/codegen.py>`_.
+
+  When using the compiler as opposed to the resolver, the additional up-front
+  processing of the FTL messages could incur a noticeable startup cost
+  (typically of the order of .5ms per message). For long running Django
+  processes this is usually a very good trade-off given the performance
+  benefits.
+
+* 'Escaper' functionality (see `escapers branch
+  <https://github.com/django-ftl/python-fluent/tree/implement_escapers>`_). This
+  allows us to `handle embedded HTML correctly
+  <https://django-ftl.readthedocs.io/en/latest/usage.html#html-escaping>`_. The
+  mechanism for doing this has been implemented as part of python-fluent in a
+  generic way, and then used in django-ftl to handle HTML escaping in templates
+  with a minimum of work.
 
 Credits
 -------