Upgrade 1171

source/applications/drivers.txt

@@ -5,10 +5,15 @@
 MongoDB Drivers and Client Libraries
 ====================================
 
-Applications communicate with MongoDB by way of a client library or
-driver that handles all interaction with the database in a language
-appropriate and sensible manner. See the following pages for more
-information about the MongoDB :ecosystem:`drivers </drivers>`:
+An application communicates with MongoDB by way of a client library,
+called a :ecosystem:`driver`, that handles all interaction with the
+database in a language appropriate to the application.
+
+Drivers
+-------
+
+See the following pages for more information about the MongoDB
+:ecosystem:`drivers </drivers>`:
 
 - JavaScript (:ecosystem:`Language Center </drivers/javascript>`, :api:`docs <js/current>`)
 - Python (:ecosystem:`Language Center </drivers/python>`, :api:`docs <python/current>`)
@@ -22,3 +27,24 @@ information about the MongoDB :ecosystem:`drivers </drivers>`:
 - C++ (:ecosystem:`Language Center </drivers/cpp>`, :api:`docs <cplusplus/current/>`)
 - Haskell (`Language Center <http://hackage.haskell.org/package/mongoDB>`_, :api:`docs <haskell/mongodb>`)
 - Erlang (:ecosystem:`Language Center </drivers/erlang>`, :api:`docs <erlang/mongodb>`)
+
+.. _drivers-version-numbers:
+
+Driver Version Numbers
+----------------------
+
+Driver version numbers use the **major.minor.patch** semantic. In a
+driver version number, the first number is the major version, the second
+the minor version, and the third indicates a patch.
+
+.. example:: Driver version numbers.
+
+   If your driver has a version number of ``2.9.1``, ``2`` is the major
+   version, ``9`` is minor, and ``1`` is the patch.
+
+The numbering scheme for drivers differs from the scheme for the MongoDB
+server, which uses the first two numbers together to designate the major
+version, with the second digit denoting the branch of the release: an odd
+second digit (i.e. 3 in 2.3.0) is a development branch, and an even second digit
+(i.e. the 4 in 2.4.0) is the stable, production-ready branch. For more information
+on server versioning, see :ref:`release-version-numbers`.

source/installation.txt

@@ -10,9 +10,10 @@ Install MongoDB
 Installation Guides
 -------------------
 
-MongoDB runs on most platforms, and supports 32-bit and 64-bit architectures.
+MongoDB runs on most platforms and supports 32-bit and 64-bit architectures.
 `10gen <http://www.10gen.com>`_, the MongoDB makers, provides both binaries
-and packages. Choose your platform below:
+and packages. In production environments, use 64-bit MongoDB binaries.
+Choose your platform below:
 
 .. _tutorials-installation:
 .. _tutorial-installation:
@@ -28,27 +29,23 @@ and packages. Choose your platform below:
    tutorial/install-mongodb-on-windows
    tutorial/install-mongodb-enterprise
 
-After you have installed MongoDB, consider the following documents as
-you begin to learn about MongoDB:
+Upgrade MongoDB
+---------------
 
 .. toctree::
    :hidden:
 
-   tutorial/getting-started
+   tutorial/upgrade-revision
 
-- :doc:`/tutorial/getting-started`
-- :doc:`/core/create`
-- :doc:`/core/read`
-- :doc:`/core/update`
-- :doc:`/core/delete`
+To upgrade to a new revision of a MongoDB major release, see the
+following document: :doc:`/tutorial/upgrade-revision`
 
 Release Notes
 -------------
 
-You should always install the latest, stable version of MongoDB.
-Stable versions have an even-numbered minor version number. For
-example: v2.4 is stable, v2.2, and v2.0 were previously the stable,
-while v2.1 and v2.3 are a development versions.
+You should always install the latest, *stable* version of MongoDB. Stable
+versions have an even number for the second number in the :ref:`version number
+<release-version-numbers>`. The following release notes are for stable versions:
 
 - Current Stable Release:
 
@@ -59,3 +56,22 @@ while v2.1 and v2.3 are a development versions.
   - :doc:`/release-notes/2.2`
   - :doc:`/release-notes/2.0`
   - :doc:`/release-notes/1.8`
+
+First Steps with MongoDB
+------------------------
+
+After you have installed MongoDB, consider the following documents as
+you begin to learn about MongoDB:
+
+.. toctree::
+   :hidden:
+
+   tutorial/getting-started
+
+- :doc:`/tutorial/getting-started`
+- :doc:`/core/create`
+- :doc:`/core/read`
+- :doc:`/core/update`
+- :doc:`/core/delete`
+- :doc:`/data-modeling`
+- :doc:`/applications/drivers`

source/release-notes.txt

@@ -57,40 +57,35 @@ Other MongoDB Release Notes
 
 .. _release-version-numbers:
 
-Version Numbers
-~~~~~~~~~~~~~~~
+MongoDB Version Numbers
+~~~~~~~~~~~~~~~~~~~~~~~
 
-There are three numbers in a MongoDB version:
+For MongoDB ``2.4.1``, ``2.4`` refers to the release series and ``.1`` refers
+to the revision. The second component of the release series (e.g. ``4``
+in ``2.4.1``) describes the type of release series. Release series ending
+with even numbers (e.g. ``4`` above) are *stable* and ready for
+production, while odd numbers are for *development* and testing only.
 
-``<major version number>.<release number>.<revision number>``
+Generally, changes in the release series (e.g. ``2.4``) mark the
+introduction of new features that may break backwards
+compatibility. Changes to the revision number mark the release
+bug fixes and backwards-compatible changes.
 
-The second number, the release number, indicates release stability. An
-odd release number indicates a release in a development series. Even
-numbered releases indicate a stable, general availability, release.
+Always upgrade to the latest stable revision of your release series.
 
-Additionally, the three numbers indicate the following:
+The version numbering system for MongoDB differs from the system
+used for the MongoDB drivers. Drivers use only the first number to indicate
+a major version. For details, see :ref:`drivers-version-numbers`.
 
-- ``<major version number>``: This rarely changes. A change to this number
-  indicates very large changes to MongoDB.
+.. example:: Version numbers
 
-- ``<release number>``: A release can include many changes, including
-  new features and updates. Some changes may break backwards
-  compatibility. See release notes for every version for compatibility
-  notes. Even-numbered release numbers are stable
-  branches. Odd-numbered release numbers are development branches.
+   - 2.0.0 : Stable release.
 
-- ``<revision number>``: This digit increments for every
-  release. Changes each revision address bugs and security issues,
+   - 2.0.1 : Revision.
 
-.. example:: Version numbers:
+   - 2.1.0 : Development release *for testing only*. Includes new features and changes for
+     testing. Interfaces and stability may not be compatible in
+     development releases.
 
-   - 1.0.0 : First stable release
-
-   - 1.0.x : Bug fixes to 1.0.x. These releases carry low risk. Always
-     upgrade to the latest revision in your release series.
-
-   - 1.1.x : Development release. Includes new features not fully finished
-     and other works-in-progress. Some things may be different than 1.0
-
-   - 1.2.x : Second stable release. This is a culmination of the 1.1.x
+   - 2.2.0 : Stable release. This is a culmination of the 2.1.x
      development series.

source/tutorial/manage-sharded-cluster-balancer.txt

@@ -158,24 +158,26 @@ all migration, use the following procedure:
 
       sh.startBalancer()
 
-.. note::
+   .. note::
 
-   If a migration is in progress, the system will complete
-   the in-progress migration. After disabling, you can use the
-   following operation in the :program:`mongo` shell to determine if
-   there are no migrations in progress:
+      If a migration is in progress, the system will complete the
+      in-progress migration before stopping. After disabling, you can use the following
+      operation in the :program:`mongo` shell to determine if there are
+      no migrations in progress:
 
-   .. code-block:: javascript
+      .. code-block:: javascript
 
-      use config
-      while( db.locks.findOne({_id: "balancer"}).state ) {
-             print("waiting..."); sleep(1000);
-      }
+         use config
+         while( sh.isBalancerRunning() ) {
+                   print("waiting...");
+                   sleep(1000);
+         }
 
-The above process and the :method:`sh.setBalancerState()`,
-:method:`sh.startBalancer()`, and :method:`sh.stopBalancer()` helpers provide
-wrappers on the following process, which may be useful if you need to
-run this operation from a driver that does not have helper functions:
+   The above process and the :method:`sh.setBalancerState()`,
+   :method:`sh.startBalancer()`, and :method:`sh.stopBalancer()` helpers
+   provide wrappers on the following process, which may be useful if you
+   need to run this operation from a driver that does not have helper
+   functions:
 
 #. Connect to any :program:`mongos` in the cluster using the
    :program:`mongo` shell.
@@ -214,7 +216,42 @@ operation:
 - :ref:`manually disable the balancer <sharding-balancing-disable-temporally>`
   for the duration of the backup procedure.
 
-Confirm that the balancer is not active using the
-:method:`sh.getBalancerState()` method before starting a backup
-operation. When the backup procedure is complete you can reactivate
+If you turn the balancer off while it is in the middle of a balancing round,
+the shut down is not instantaneous. The balancer completes the chunk
+move in-progress and then ceases all further balancing rounds.
+
+Before starting a backup operation, confirm that the balancer is not
+active. You can use the following command to determine if the balancer
+is active:
+
+.. code-block:: javascript
+
+   !sh.getBalancerState() && !sh.isBalancerRunning()
+
+When the backup procedure is complete you can reactivate
 the balancer process.
+
+.. _sharding-balancing-re-enable:
+
+Re-enable the Balancer after Temporarily Disabling It
+-----------------------------------------------------
+
+Use this procedure if you have temporarily disabled the balancer and are
+ready to re-enable it:
+
+#. Connect to any :program:`mongos` in the cluster using the
+   :program:`mongo` shell.
+
+#. Issue one of the following operations to enable the balancer:
+
+   - From the :program:`mongo` shell, issue:
+
+     .. code-block:: javascript
+
+        sh.startBalancer()
+
+   - From a driver that does not have the :method:`sh.startBalancer()` helper:
+
+     .. code-block:: javascript
+
+        db.settings.update( { _id: "balancer" }, { $set : { stopped: false } } , true );