Add readme entry to lock file to explain what it is

doc/01-basic-usage.md

@@ -119,8 +119,15 @@ to those specific versions.
 
 This is important because the `install` command checks if a lock file is present,
 and if it is, it downloads the versions specified there (regardless of what `composer.json`
-says). This means that anyone who sets up the project will download the exact
+says).
-same version of the dependencies.
+
+This means that anyone who sets up the project will download the exact
+same version of the dependencies. Your CI server, production machines, other
+developers in your team, everything and everyone runs on the same dependencies, which
+mitigates the potential for bugs affecting only some parts of the deployments. Even if you
+develop alone, in six months when reinstalling the project you can feel confident the
+dependencies installed are still working even if your dependencies released
+many new versions since then.
 
 If no `composer.lock` file exists, Composer will read the dependencies and
 versions from `composer.json` and  create the lock file.
@@ -132,6 +139,10 @@ the lock file with the new version.
 
     $ php composer.phar update
 
+If you only want to install or update one dependency, you can whitelist them:
+
+    $ php composer.phar update monolog/monolog [...]
+
 > **Note:** For libraries it is not necessarily recommended to commit the lock file,
 > see also: [Libraries - Lock file](02-libraries.md#lock-file).
 

src/Composer/Package/Locker.php

@@ -204,6 +204,7 @@ class Locker
     public function setLockData(array $packages, $devPackages, array $platformReqs, $platformDevReqs, array $aliases, $minimumStability, array $stabilityFlags)
     {
         $lock = array(
+            '_readme' => array('This file locks the dependencies of your project to a known state', 'Read more about it at http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file'),
             'hash' => $this->hash,
             'packages' => null,
             'packages-dev' => null,

tests/Composer/Test/Package/LockerTest.php

@@ -120,6 +120,7 @@ class LockerTest extends \PHPUnit_Framework_TestCase
             ->expects($this->once())
             ->method('write')
             ->with(array(
+                '_readme' => array('This file locks the dependencies of your project to a known state', 'Read more about it at http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file'),
                 'hash' => 'md5',
                 'packages' => array(
                     array('name' => 'pkg1', 'version' => '1.0.0-beta'),