Merge branch '2.0'

doc/01-basic-usage.md

@@ -20,14 +20,14 @@ to find the file at the top of your VCS repository.
 
 ### The `require` key
 
-The first (and often only) thing you specify in `composer.json` is the
+The first thing you specify in `composer.json` is the
 [`require`](04-schema.md#require) key. You are telling Composer which
 packages your project depends on.
 
 ```json
 {
     "require": {
-        "monolog/monolog": "1.0.*"
+        "monolog/monolog": "2.0.*"
     }
 }
 ```
@@ -38,11 +38,11 @@ As you can see, [`require`](04-schema.md#require) takes an object that maps
 
 Composer uses this information to search for the right set of files in package
 "repositories" that you register using the [`repositories`](04-schema.md#repositories)
-key, or in Packagist, the default package repository. In the above example,
-since no other repository has been registered in the `composer.json` file, it is
-assumed that the `monolog/monolog` package is registered on Packagist. (See more
-about Packagist [below](#packagist), or read more about repositories
-[here](05-repositories.md)).
+key, or in [Packagist.org](https://packagist.org), the default package repository.
+In the above example, since no other repository has been registered in the
+`composer.json` file, it is assumed that the `monolog/monolog` package is registered
+on Packagist.org. (See more about Packagist [below](#packagist), or read more
+about repositories [here](05-repositories.md)).
 
 ### Package names
 
@@ -59,9 +59,9 @@ you to require certain versions of server software. See
 ### Package version constraints
 
 In our example, we are requesting the Monolog package with the version constraint
-[`1.0.*`](https://semver.mwl.be/#?package=monolog%2Fmonolog&version=1.0.*).
-This means any version in the `1.0` development branch, or any version that is
-greater than or equal to 1.0 and less than 1.1 (`>=1.0 <1.1`).
+[`2.0.*`](https://semver.mwl.be/#?package=monolog%2Fmonolog&version=2.0.*).
+This means any version in the `2.0` development branch, or any version that is
+greater than or equal to 2.0 and less than 2.1 (`>=2.0 <2.1`).
 
 Please read [versions](articles/versions.md) for more in-depth information on
 versions, how versions relate to each other, and on version constraints.
@@ -71,9 +71,9 @@ versions, how versions relate to each other, and on version constraints.
 > and searches for it in any repositories that you have registered using the
 > [`repositories`](04-schema.md#repositories) key. If you have not registered
 > any extra repositories, or it does not find a package with that name in the
-> repositories you have specified, it falls back to Packagist (more [below](#packagist)).
+> repositories you have specified, it falls back to Packagist.org (more [below](#packagist)).
 >
-> When Composer finds the right package, either in Packagist or in a repo you have specified,
+> When Composer finds the right package, either in Packagist.org or in a repo you have specified,
 > it then uses the versioning features of the package's VCS (i.e., branches and tags)
 > to attempt to find the best match for the version constraint you have specified. Be sure to read
 > about versions and package resolution in the [versions article](articles/versions.md).
@@ -89,54 +89,35 @@ versions, how versions relate to each other, and on version constraints.
 
 ## Installing dependencies
 
-To install the defined dependencies for your project, run the
-[`install`](03-cli.md#install-i) command.
+To initially install the defined dependencies for your project, you should run the
+[`update`](03-cli.md#update-u) command.
 
 ```sh
-php composer.phar install
+php composer.phar update
 ```
 
-When you run this command, one of two things may happen:
+This will make Composer do two things:
 
-### Installing without `composer.lock`
-
-If you have never run the command before and there is also no `composer.lock` file present,
-Composer resolves all dependencies listed in your `composer.json` file and downloads
-the latest version of their files into the `vendor` directory in your project. (The `vendor`
+- It resolves all dependencies listed in your `composer.json` file and writes all of the
+  packages and their exact versions to the `composer.lock` file, locking the project to
+  those specific versions. You should commit the `composer.lock` file to your project repo
+  so that all people working on the project are locked to the same versions of dependencies
+  (more below). This is the main role of the `update` command.
+- It then implicitly runs the [`install`](03-cli.md#install-i) command. This will download
+  the dependencies' files into the `vendor` directory in your project. (The `vendor`
   directory is the conventional location for all third-party code in a project). In our
   example from above, you would end up with the Monolog source files in
-`vendor/monolog/monolog/`. If Monolog listed any dependencies, those would also be in
-folders under `vendor/`.
+  `vendor/monolog/monolog/`. As Monolog has a dependency on `psr/log`, that package's files
+  can also be found inside `vendor/`.
 
 > **Tip:** If you are using git for your project, you probably want to add
 > `vendor` in your `.gitignore`. You really don't want to add all of that
 > third-party code to your versioned repository.
 
-When Composer has finished installing, it writes all of the packages and the exact versions
-of them that it downloaded to the `composer.lock` file, locking the project to those specific
-versions. You should commit the `composer.lock` file to your project repo so that all people
-working on the project are locked to the same versions of dependencies (more below).
-
-### Installing with `composer.lock`
-
-This brings us to the second scenario. If there is already a `composer.lock` file as well as a
-`composer.json` file when you run `composer install`, it means either you ran the
-`install` command before, or someone else on the project ran the `install` command and
-committed the `composer.lock` file to the project (which is good).
-
-Either way, running `install` when a `composer.lock` file is present resolves and installs
-all dependencies that you listed in `composer.json`, but Composer uses the exact versions listed
-in `composer.lock` to ensure that the package versions are consistent for everyone
-working on your project. As a result you will have all dependencies requested by your
-`composer.json` file, but they may not all be at the very latest available versions
-(some of the dependencies listed in the `composer.lock` file may have released newer versions since
-the file was created). This is by design, it ensures that your project does not break because of
-unexpected changes in dependencies.
-
 ### Commit your `composer.lock` file to version control
 
-Committing this file to VC is important because it will cause anyone who sets
-up the project to use the exact same
+Committing this file to version control is important because it will cause anyone
+who sets up the project to use the exact same
 versions of the dependencies that you are using. 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
@@ -148,14 +129,36 @@ still working even if your dependencies released many new versions since then.
 > **Note:** For libraries it is not necessary to commit the lock
 > file, see also: [Libraries - Lock file](02-libraries.md#lock-file).
 
+### Installing from `composer.lock`
+
+If there is already a `composer.lock` file in the project folder, it means either
+you ran the `update` command before, or someone else on the project ran the `update`
+command and committed the `composer.lock` file to the project (which is good).
+
+Either way, running `install` when a `composer.lock` file is present resolves and installs
+all dependencies that you listed in `composer.json`, but Composer uses the exact versions listed
+in `composer.lock` to ensure that the package versions are consistent for everyone
+working on your project. As a result you will have all dependencies requested by your
+`composer.json` file, but they may not all be at the very latest available versions
+(some of the dependencies listed in the `composer.lock` file may have released newer versions since
+the file was created). This is by design, it ensures that your project does not break because of
+unexpected changes in dependencies.
+
+So after fetching new changes from your VCS repository it is recommended to run
+a Composer `install` to make sure the vendor directory is up in sync with your
+`composer.lock` file.
+
+```sh
+php composer.phar install
+```
+
 ## Updating dependencies to their latest versions
 
 As mentioned above, the `composer.lock` file prevents you from automatically getting
 the latest versions of your dependencies. To update to the latest versions, use the
 [`update`](03-cli.md#update-u) command. This will fetch the latest matching
 versions (according to your `composer.json` file) and update the lock file
-with the new versions. (This is equivalent to deleting the `composer.lock` file
-and running `install` again.)
+with the new versions.
 
 ```sh
 php composer.phar update
@@ -173,13 +176,13 @@ php composer.phar update monolog/monolog [...]
 
 ## Packagist
 
-[Packagist](https://packagist.org/) is the main Composer repository. A Composer
+[Packagist.org](https://packagist.org/) is the main Composer repository. A Composer
 repository is basically a package source: a place where you can get packages
 from. Packagist aims to be the central repository that everybody uses. This
 means that you can automatically `require` any package that is available there,
 without further specifying where Composer should look for the package.
 
-If you go to the [Packagist website](https://packagist.org/) (packagist.org),
+If you go to the [Packagist.org website](https://packagist.org/),
 you can browse and search for packages.
 
 Any open source project using Composer is recommended to publish their packages
@@ -222,7 +225,7 @@ require __DIR__ . '/vendor/autoload.php';
 
 $log = new Monolog\Logger('name');
 $log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
-$log->addWarning('Foo');
+$log->warning('Foo');
 ```
 
 You can even add your own code to the autoloader by adding an

src/Composer/Installer.php

@@ -206,7 +206,7 @@ class Installer
 
         // Force update if there is no lock file present
         if (!$this->update && !$this->locker->isLocked()) {
-            $this->io->writeError('<warning>No lock file found. Updating dependencies instead of installing from lock file. Use composer update over composer install if you do not have a lock file.</warning>');
+            $this->io->writeError('<warning>No composer.lock file present. Updating dependencies to latest instead of installing from lock file. See https://getcomposer.org/install for more information.</warning>');
             $this->update = true;
         }