From 069109e0f0c564abab7ee7fa5020714bfd20a017 Mon Sep 17 00:00:00 2001
From: Jordi Boggiano <j.boggiano@seld.be>
Date: Mon, 8 Apr 2013 18:15:08 +0200
Subject: [PATCH] Add readme entry to lock file to explain what it is

---
 doc/01-basic-usage.md                      | 15 +++++++++++++--
 src/Composer/Package/Locker.php            |  1 +
 tests/Composer/Test/Package/LockerTest.php |  1 +
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md
index 7b3434328..09f0ae5bc 100644
--- a/doc/01-basic-usage.md
+++ b/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
-same version of the dependencies.
+says).
+
+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).
 
diff --git a/src/Composer/Package/Locker.php b/src/Composer/Package/Locker.php
index 4f165ce57..efdbb516c 100644
--- a/src/Composer/Package/Locker.php
+++ b/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,
diff --git a/tests/Composer/Test/Package/LockerTest.php b/tests/Composer/Test/Package/LockerTest.php
index d72a43363..09d31439f 100644
--- a/tests/Composer/Test/Package/LockerTest.php
+++ b/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'),