diff docs/index.rst @ 977:cc0f0d94bf30

docs: rewrite index page (including dangling links to future docs)

This has been reviewed to death on the evolve-testers mailing list.
I've made some minor tweaks since the last round of reviews, but the
main content is the same.

--- a/docs/index.rst	Fri Jun 06 17:43:45 2014 -0400
+++ b/docs/index.rst	Thu Jun 05 21:57:34 2014 -0400
@@ -1,166 +1,105 @@
-.. Copyright 2011 Pierre-Yves David <[e-mail]>
-..                Logilab SA        <[e-mail]>
-
-========================================
-Changeset Evolution Experimentation
-========================================
-
+.. Copyright © 2014 Greg Ward <[e-mail]>
 
-This is the online documentation of the `evolve extension`_. An experimental
-extension that drive the implementation of the `changeset evolution concept`_ for
-Mercurial.
+==================================
+Changeset Evolution with Mercurial
+==================================
 
-.. _`evolve extension`: http://mercurial.selenic.com/wiki/EvolveExtension
-.. _`changeset evolution concept`: http://mercurial.selenic.com/wiki/ChangesetEvolution
+`evolve`_ is an experimental Mercurial extension for safe mutable history.
 
-Here are various materials on planned improvement to Mercurial regarding
-rewriting history.
+.. _`evolve`: http://mercurial.selenic.com/wiki/EvolveExtension
 
-First, read about what challenges arise while rewriting history and how we plan to
-solve them once and for all.
-
-.. toctree::
-   :maxdepth: 2
-
-   instability
-
-The effort is split in two parts:
+With core Mercurial, changesets are permanent and immutable. You can
+commit new changesets to modify your source code, but you cannot
+modify or remove old changesets—they are carved in stone for all
+eternity.
 
- * The **obsolescence marker** concept aims to provide an alternative to ``strip``
-   to get rid of changesets. This concept has been partially implemented since
-   Mercurial 2.3.
+For years, Mercurial has included various extensions that allow
+history modification: ``rebase``, ``mq``, ``histedit``, and so forth.
+These are useful and popular extensions, and in fact history
+modification is one of the big reasons DVCSes (distributed version
+control systems) like Mercurial took off.
 
- * The **evolve** Mercurial extension rewrites history using obsolete
-   *marker* under the hood.
-
-The first and most important step is by far the **obsolescence marker**. However
-most users will never be directly exposed to the concept. For this reason
-this manual starts with changeset evolution.
+But there's a catch: until now, Mercurial's various mechanisms for
+modifying history have been *unsafe*, in that changesets were
+destroyed (“stripped”) rather than simply made invisible.
 
-Evolve: A robust alternative to MQ
-====================================
-
-Evolve is an experimental history rewriting extension that uses obsolete
-markers. It is inspired by MQ and pbranch but has multiple advantages over
-them:
-
-* Focus on your current work.
+``evolve`` makes things better in a couple of ways:
 
-    You can focus your work on a single changeset and take care of adapting
-    descendent changesets later.
-
-* Handle **non-linear history with branches and merges**
+  * It changes the behaviour of most existing history modification
+    extensions (``rebase``, ``histedit``, etc.) so they use a safer
+    mechanism (*changeset obsolescence*, covered below) rather than
+    the older, less safe *strip* operation.
 
-* Rely internally on Mercurial's **robust merge** mechanism.
+  * It provides a new way of modifying history that is roughly
+    equivalent to ``mq`` (but much nicer and safer).
 
-  Simple conflicts are handled by real merge tools using the appropriate ancestor.
-  Conflicts are much rarer and much more user friendly.
+It helps to understand that ``evolve`` builds on infrastructure
+already in core Mercurial:
 
-*  Mutable history **fully available all the time**.
-
-  Always use 'hg update' and forget about (un)applying patches to access the
-  mutable part of your history.
-
-
-* Use only **plain changesets** and forget about patches. Evolve will create and
-  exchange real changesets. Mutable history can be used in all usual operations:
-  pull, push, log, diff, etc.
+  * *Phases* (starting in Mercurial 2.1) allow you to distinguish
+    mutable and immutable changesets. We'll cover phases early in the
+    user guide, since understanding phases is essential to
+    understanding ``evolve``.
 
-* Allow **sharing and collaboration** mutable history without fear of duplicates
-  (thanks to obsolete marker).
-
-* Cover all MQ usage but guard.
-
-.. warning:: The evolve extension and obsolete markers are at an experimental
-             stage. While using obsolete you willl likely be exposed to complex
-             implications of the **obsolete marker** concept. I do not recommend
-             non-power users to test this at this stage.
+  * *Changeset obsolescence* (starting in Mercurial 2.3) is how
+    Mercurial knows how history has been modified, specifically when
+    one changeset replaces another. In the obsolescence model, a
+    changeset is neither removed nor modified, but is instead marked
+    *obsolete* and typically replaced by a *successor*. Obsolete
+    changesets usually become *hidden* as well. Obsolescence is an
+    invisible feature until you start using ``evolve``, so we'll cover
+    it in the user guide too.
 
-             While numbered 1.0.0, the command line API of this version should
-             **not** be regarded as *stable*: command behavior, name and
-             options may change in future releases or once integrated into
-             Mercurial. It is still an immature extension; a lot of
-             features are still missing but there is low risk of
-             repository corruption.
-
-             Production-ready version should hide such details from normal users.
+Some of the things you can do with ``evolve`` are:
 
-The evolve extension requires Mercurial 2.5 (older versions supports down to 2.2)
-
-To enable the evolve extension use::
-
-    $ hg clone https://bitbucket.org/marmoute/mutable-history -u stable
-    $ echo '[extensions]\nevolve=$PWD/mutable-history/hgext/evolve.py' >> ~/.hgrc
-
-You will probably want to use hgview_ to visualize obsolescence. Version 1.7.1
-or later is required.
-
-.. _hgview: http://www.logilab.org/project/hgview/
+  * Fix a mistake immediately: “Oops! I just committed a changeset
+    with a syntax error—I'll fix that and amend the changeset so no
+    one sees my mistake.” (While this is possible using existing
+    features of core Mercurial, ``evolve`` makes it safer.)
 
-
- ---
-
-For more information see the documents below:
-
-.. toctree::
-   :maxdepth: 1
+  * Fix a mistake a little bit later: “Oops! I broke the tests three
+    commits back, but only noticed it now—I'll just update back to the
+    bad changeset, fix my mistake, amend the changeset, and evolve
+    history to update the affected changesets.”
 
-   tutorials/tutorial
-   evolve-good-practice
-   evolve-faq
-   from-mq
-   evolve-collaboration
-   qsync
+  * Remove unwanted changes: “I hacked in some debug output two
+    commits back; everything is working now, so I'll just prune that
+    unwanted changeset and evolve history before pushing.”
 
-Smart changeset deletion: Obsolete Marker
-==========================================
-
-The obsolete marker is a powerful concept that allows Mercurial to safely handle
-history rewriting operations. It is a new type of relation between Mercurial
-changesets that tracks the result of history rewriting operations.
+  * Share mutable history with yourself: say you do most of your
+    programming work locally, but need to test on a big remote server
+    somewhere before you know everything is good. You can use
+    ``evolve`` to share mutable history between two computers, pushing
+    finely polished changesets to a public repository only after
+    testing on the test server.
 
-This concept is simple to define and provides a very solid base for:
-
-- very fast history rewriting operations
-
-- auditable and reversible history rewriting process
-
-- clean final history
-
-- share and collaborate on mutable parts of the history
+  * Share mutable history for code review: you don't want to publish
+    unreviewed changesets, but you can't block every commit waiting
+    for code review. The solution is to share mutable history with
+    your reviewer, amending each changeset until it passes review.
 
-- gracefully handle history rewriting conflicts
-
-- allow various history rewriting UI to collaborate with a underlying common API
+``evolve`` is experimental!
+---------------------------
 
- ---
+TODO
 
-For more information, see the documents below
-
-.. toctree::
-   :maxdepth: 1
+  * unstable UI
+  * some corner cases not covered yet
 
-   obs-concept
-   obs-terms
-   obs-implementation
-
+Installation and setup
+----------------------
 
-Known limitations and bugs
-=================================
-
-Here is a list of known issues that will be fixed later:
-
+TODO
 
-* You need to provide to `graft --continue -O` if you started you
-  graft using `-O`.
-
-  you to manually specify target all the time.
-
-* Trying to exchange obsolete marker with a static http repo will crash.
+Next steps:
+  * For a practical guide to using ``evolve`` in a single repository,
+    see the `user guide`_ (coming soon).
+  * For more advanced tricks, see `sharing mutable history`_ (coming soon).
+  * To learn about the concepts underlying ``evolve``, see `concepts`_
+    (coming soon).
+  * If you're coming from MQ, see the `MQ migration guide`_ (incomplete).
 
-* Extinct changesets are hidden using the *hidden* feature of mercurial only
-  supported by a few commands.
-
-  Only ``hg log``, ``hgview`` and `hg glog` support it. Neither ``hg heads`` nor other visual viewers do.
-
-* hg heads shows extinct changesets.
+.. _`user guide`: user-guide.html
+.. _`concepts`: concepts.html
+.. _`sharing mutable history`: sharing.html
+.. _`MQ migration guide`: from-mq.html