DOCS-654 review edits

Author: Bob Grabar

source/release-notes/2.0.txt

@@ -42,26 +42,6 @@ In addition, you may see reduced write throughput.
 :program:`mongod` instances; however, for best results, upgrade your
 deployments using the following procedures:
 
-.. _2.0-convert-to-new-index-format:
-
-Converting an Existing Index to the New Format
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To convert all indexes for a given collection to the
-:ref:`2.0 type <2.0-new-index-format>`, invoke the
-:doc:`compact </reference/command/compact>` command.
-
-All operations that create a new index will result in a 2.0 index by
-default. For example:
-
-- Reindexing results on an older-version index results in a 2.0 index.
-  However, reindexing on a secondary does *not* work in versions prior
-  to 2.0. Do not reindex on a secondary. For a workaround, see
-  :issue:`SERVER-3866`.
-
-- The :setting:`repair` database command converts indexes to a 2.0
-  indexes.
-
 .. _2.0-upgrade-standalone:
 
 Upgrading a Standalone ``mongod``
@@ -163,10 +143,23 @@ type are realized only if you create a new index or re-index an old one.
 Dates are now signed, and the max index key size has increased slightly
 from 819 to 1024 bytes.
 
-Once you create new indexes, downgrading to 1.8.x will require a
-re-index of any indexes created using 2.0.
+All operations that create a new index will result in a 2.0 index by
+default. For example:
+
+- Reindexing results on an older-version index results in a 2.0 index.
+  However, reindexing on a secondary does *not* work in versions prior
+  to 2.0. Do not reindex on a secondary. For a workaround, see
+  :issue:`SERVER-3866`.
 
-.. seealso:: :ref:`2.0-convert-to-new-index-format`
+- The :setting:`repair` database command converts indexes to a 2.0
+  indexes.
+
+To convert all indexes for a given collection to the :ref:`2.0 type
+<2.0-new-index-format>`, invoke the :dbcommand:`compact` command.
+
+Once you create new indexes, downgrading to 1.8.x will require a
+re-index of any indexes created using 2.0. See
+:doc:`/tutorial/roll-back-to-v18-index`.
 
 Sharding Authentication
 ~~~~~~~~~~~~~~~~~~~~~~~

source/tutorial.txt

@@ -55,6 +55,7 @@ Development Patterns
    tutorial/create-an-auto-incrementing-field
    tutorial/enforce-unique-keys-for-sharded-collections
    tutorial/aggregation-examples
+   tutorial/roll-back-to-v18-index
 
 .. index:: tutorials; application development
 .. index:: application tutorials

source/tutorial/roll-back-to-v18-index.txt

@@ -1,46 +1,53 @@
-================================
-Roll Back to a Version 1.8 Index
-================================
+=======================
+Build Old Style Indexes
+=======================
 
 .. default-domain:: mongodb
 
+.. important::
 
-MongoDB version 2.0 and later supports the old index format. But old versions
-will not support the new format. If you need to roll back to an older
-version, the server will run, but queries and other operations involving
-the newer indexes will log and return an error. Thus, you will need to
-re-create any new index you would like to use on an old server.
-
-Versions prior to 1.8.2, inclusive, are not aware of the index version
-field. If you rollback a ``{v:1}`` index to 1.8.2 and re-index it, its
-version will still be marked ``{v: 1}``, although it actual is now version ``{v:0}``.
-If you upgrade again to 2.0, this index will not work, even though it is
-marked as ``{v: 1}`` in ``system.indexes``. If you must roll back to a
-version prior to 1.8.2, you must delete the index then create it again
-(instead of simply re-indexing).
-
-Building a {v:0} Index
-----------------------
-
-You can still create a ``{v:0}`` index with MongoDB version 2.0 or later. To do so, add the
-option ``{v:0}`` in the index creation command. For example in the :program:`mongo`
-shell:
-
-.. code-block:: javascript
-
-   // defaults to a v:1 index
-   db.foo.ensureIndex({name:1})
-   db.system.indexes.find()
-   { "v" : 1, "key" : { "_id" : 1 }, "ns" : "mydb.foo", "name" : "_id_" }
-   { "v" : 1, "key" : { "name" : 1 }, "ns" : "mydb.foo", "name" : "name_1" }
-   db.foo.dropIndex({name:1})
-   { "nIndexesWas" : 2, "ok" : 1 }
-
-   // create a v:0 index
-   db.foo.ensureIndex({name:1},{v:0})
-   db.system.indexes.find()
-   { "v" : 1, "key" : { "_id" : 1 }, "ns" : "mydb.foo", "name" : "_id_" }
-   
-   { "v" : 0, "key" : { "name" : 1 }, "ns" : "mydb.foo", "name" : "name_1" }
-
-.. seealso:: :ref:`2.0-new-index-format` and :ref:`2.0-convert-to-new-index-format`
+   Use this procedure *only* if you must have indexes that are compatible
+   with a version of MongoDB earlier than 2.0.
+
+MongoDB version 2.0 introduced the ``{v:1}`` index format. MongoDB
+versions 2.0 and later support both the ``{v:1}`` format and the
+earlier ``{v:0}`` format.
+
+MongoDB versions prior to 1.8.2, however, support only the ``{v:0}``
+format. If you need to roll back MongoDB to a version prior to 2.0, you
+must *drop* and *re-create* your indexes.
+
+You do so using the :method:`dropIndexes()
+<db.collection.dropIndexes()>` and :method:`ensureIndex()
+<db.collection.ensureIndex()>` methods. You *cannot* simply reindex the
+collection. If you simply reindex, the ``v`` fields in your indexes
+would still hold values of ``1``, even though the indexes would now use
+the ``{v:0}`` format. If you were to upgrade again to version 2.0 or
+later, your indexes would not work.
+
+.. example::
+
+   Suppose you rolled back from MongoDB 2.0 to MongoDB 1.8, and suppose
+   you had the following index on the ``items`` collection:
+
+   .. code-block:: javascript
+
+      { "v" : 1, "key" : { "name" : 1 }, "ns" : "mydb.items", "name" : "name_1" }
+
+   The ``v`` field tells you the index is a ``{v:1}`` index, which
+   is incompatible with version 1.8.
+
+   To drop the index, issue the following command:
+
+   .. code-block:: javascript
+
+      db.items.dropIndex( { name : 1 } )
+
+   To recreate the index as a ``{v:0}`` index, issue the following
+   command:
+
+   .. code-block:: javascript
+
+      db.foo.ensureIndex( { name : 1 } , { v : 0 } )
+
+.. seealso:: :ref:`2.0-new-index-format`.