diff -r 14f91037d2f6 -r c94aaf6df69c docs/index.rst
--- a/docs/index.rst	Tue Apr 14 12:58:13 2015 -0400
+++ b/docs/index.rst	Mon Apr 13 15:00:05 2015 -0400
@@ -81,17 +81,51 @@
 ``evolve`` is experimental!
 ---------------------------
 
-TODO
+The long-term plan for ``evolve`` is to add it to core Mercurial.
+However, it is not yet stable enough for that. In particular:
+
+  * The UI is unstable: ``evolve``'s command names and command options
+    are not completely nailed down yet. They are subject to occasional
+    backwards-incompatible changes. If you write scripts that use
+    evolve commands, a future release could break your scripts.
 
-  * unstable UI
-  * some corner cases not covered yet
+  * There are still some corner cases that aren't handled yet. If you
+    think you have found such a case, please check if it's already
+    described in the Mercurial bug tracker (http://bz.selenic.com).
+    Bugs in ``evolve`` are files under component "evolution": use
+    `this query`_ to view open bugs in ``evolve``.
+
+.. _`this query`: http://bz.selenic.com/buglist.cgi?component=evolution&bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=NEED_EXAMPLE
 
 Installation and setup
 ----------------------
 
-TODO
+To use ``evolve``, you must:
+
+  #. Clone the ``evolve`` repository::
+
+       cd ~/src
+       hg clone https://bitbucket.org/marmoute/mutable-history
+
+  #. Configure the extension, either locally ::
+
+       hg config --local
+
+     or for all your repositories ::
+
+       hg config --edit
+
+     Then add ::
+
+       evolve=~/src/mutable-history/hgext/evolve.py
+
+     in the ``[extensions]`` section (adding the section if necessary). Use
+     the directory that you actually cloned to, of course.
+
 
 Next steps:
+-----------
+
   * For a practical guide to using ``evolve`` in a single repository,
     see the `user guide`_.
   * For more advanced tricks, see `sharing mutable history`_.