Merge remote-tracking branch 'alcohol/split-schema-documentation'

doc/00-intro.md

@@ -1,54 +1,41 @@
 # Introduction
 
 Composer is a tool for dependency management in PHP. It allows you to declare
-the dependent libraries your project needs and it will install them in your
-project for you.
+the libraries your project depends on and it will manage (install/update) them
+for you.
 
 ## Dependency management
 
-Composer is not a package manager. Yes, it deals with "packages" or libraries, but
-it manages them on a per-project basis, installing them in a directory (e.g. `vendor`)
-inside your project. By default it will never install anything globally. Thus,
-it is a dependency manager.
+Composer is **not** a package manager in the same sense as Yum or Apt are. Yes,
+it deals with "packages" or libraries, but it manages them on a per-project
+basis, installing them in a directory (e.g. `vendor`) inside your project. By
+default it will never install anything globally. Thus, it is a dependency
+manager.
 
-This idea is not new and Composer is strongly inspired by node's [npm](https://npmjs.org/)
-and ruby's [bundler](http://bundler.io/). But there has not been such a tool
-for PHP.
+This idea is not new and Composer is strongly inspired by node's
+[npm](https://npmjs.org/) and ruby's [bundler](http://bundler.io/).
 
-The problem that Composer solves is this:
+Suppose:
 
 a) You have a project that depends on a number of libraries.
 
 b) Some of those libraries depend on other libraries.
 
-c) You declare the things you depend on.
+Composer:
 
-d) Composer finds out which versions of which packages need to be installed, and
-   installs them (meaning it downloads them into your project).
-
-## Declaring dependencies
+c) Enables you to declare the libraries you depend on.
 
-Let's say you are creating a project, and you need a library that does logging.
-You decide to use [monolog](https://github.com/Seldaek/monolog). In order to
-add it to your project, all you need to do is create a `composer.json` file
-which describes the project's dependencies.
-
-```json
-{
-    "require": {
-        "monolog/monolog": "1.2.*"
-    }
-}
-```
+d) Finds out which versions of which packages can and need to be installed, and
+   installs them (meaning it downloads them into your project).
 
-We are simply stating that our project requires some `monolog/monolog` package,
-any version beginning with `1.2`.
+See the [Basic usage](01-basic-usage.md) chapter for more details on declaring
+dependencies.
 
 ## System Requirements
 
 Composer requires PHP 5.3.2+ to run. A few sensitive php settings and compile
-flags are also required, but when using the installer you will be warned about any
-incompatibilities.
+flags are also required, but when using the installer you will be warned about
+any incompatibilities.
 
 To install packages from sources instead of simple zip archives, you will need
 git, svn or hg depending on how the package is version-controlled.
@@ -60,6 +47,12 @@ Linux and OSX.
 
 ### Downloading the Composer Executable
 
+Composer offers a convenient installer that you can execute directly from the
+commandline. Feel free to [download this file](https://getcomposer.org/installer)
+or review it on [GitHub](https://github.com/composer/getcomposer.org/blob/master/web/installer)
+if you wish to know more about the inner workings of the installer. The source
+is plain PHP.
+
 There are in short, two ways to install Composer. Locally as part of your
 project, or globally as a system wide executable.
 
@@ -79,37 +72,54 @@ curl -sS https://getcomposer.org/installer | php
 php -r "readfile('https://getcomposer.org/installer');" | php
 ```
 
-The installer will just check a few PHP settings and then download `composer.phar`
-to your working directory. This file is the Composer binary. It is a PHAR (PHP
-archive), which is an archive format for PHP which can be run on the command
-line, amongst other things.
+The installer will just check a few PHP settings and then download
+`composer.phar` to your working directory. This file is the Composer binary. It
+is a PHAR (PHP archive), which is an archive format for PHP which can be run on
+the command line, amongst other things.
+
+Now just run `php composer.phar` in order to run Composer.
 
 You can install Composer to a specific directory by using the `--install-dir`
-option and providing a target directory (it can be an absolute or relative path):
+option and additionally (re)name it as well using the `--filename` option:
 
 ```sh
-curl -sS https://getcomposer.org/installer | php -- --install-dir=bin
+curl -sS https://getcomposer.org/installer | php -- --install-dir=bin --filename=composer
 ```
 
+Now just run `php bin/composer` in order to run Composer.
+
 #### Globally
 
-You can place this file anywhere you wish. If you put it in your `PATH`,
-you can access it globally. On unixy systems you can even make it
-executable and invoke it without `php`.
+You can place the Composer PHAR anywhere you wish. If you put it in a directory
+that is part of your `PATH`, you can access it globally. On unixy systems you
+can even make it executable and invoke it without directly using the `php`
+interpreter.
 
-You can run these commands to easily access `composer` from anywhere on your system:
+Run these commands to globally install `composer` on your system:
 
 ```sh
 curl -sS https://getcomposer.org/installer | php
 mv composer.phar /usr/local/bin/composer
 ```
 
-> **Note:** If the above fails due to permissions, run the `mv` line
-> again with sudo.
+> **Note:** If the above fails due to permissions, run the `mv` line again 
+> with sudo.
+
+A quick copy-paste version including sudo:
 
-> **Note:** In OSX Yosemite the `/usr` directory does not exist by default. If you receive the error "/usr/local/bin/composer: No such file or directory" then you must create `/usr/local/bin/` manually before proceeding.
+```sh
+curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer
+```
 
-Then, just run `composer` in order to run Composer instead of `php composer.phar`.
+> **Note:** On some versions of OSX the `/usr` directory does not exist by
+> default. If you receive the error "/usr/local/bin/composer: No such file or
+> directory" then you must create the directory manually before proceeding:
+> `mkdir -p /usr/local/bin`.
+
+> **Note:** For information on changing your PATH, please read the
+> [Wikipedia article](https://en.wikipedia.org/wiki/PATH_(variable)) and/or use Google.
+
+Now just run `composer` in order to run Composer instead of `php composer.phar`.
 
 ## Installation - Windows
 
@@ -117,24 +127,26 @@ Then, just run `composer` in order to run Composer instead of `php composer.phar
 
 This is the easiest way to get Composer set up on your machine.
 
-Download and run [Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe),
-it will install the latest Composer version and set up your PATH so that you can
-just call `composer` from any directory in your command line.
+Download and run
+[Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe). It will
+install the latest Composer version and set up your PATH so that you can just
+call `composer` from any directory in your command line.
 
-> **Note:** Close your current terminal. Test usage with a new terminal:
-> That is important since the PATH only gets loaded when the terminal starts.
+> **Note:** Close your current terminal. Test usage with a new terminal: This is
+> important since the PATH only gets loaded when the terminal starts.
 
 ### Manual Installation
 
 Change to a directory on your `PATH` and run the install snippet to download
-composer.phar:
+`composer.phar`:
 
 ```sh
 C:\Users\username>cd C:\bin
 C:\bin>php -r "readfile('https://getcomposer.org/installer');" | php
 ```
 
-> **Note:** If the above fails due to readfile, use the `http` url or enable php_openssl.dll in php.ini
+> **Note:** If the above fails due to readfile, use the `http` url or enable
+> php_openssl.dll in php.ini
 
 Create a new `composer.bat` file alongside `composer.phar`:
 
@@ -153,38 +165,7 @@ Composer version 27d8904
 
 ## Using Composer
 
-We will now use Composer to install the dependencies of the project. If you
-don't have a `composer.json` file in the current directory please skip to the
-[Basic Usage](01-basic-usage.md) chapter.
-
-To resolve and download dependencies, run the `install` command:
-
-```sh
-php composer.phar install
-```
-
-If you did a global install and do not have the phar in that directory
-run this instead:
-
-```sh
-composer install
-```
-
-Following the [example above](#declaring-dependencies), this will download
-monolog into the `vendor/monolog/monolog` directory.
-
-## Autoloading
-
-Besides downloading the library, Composer also prepares an autoload file that's
-capable of autoloading all of the classes in any of the libraries that it
-downloads. To use it, just add the following line to your code's bootstrap
-process:
-
-```php
-require __DIR__ . '/vendor/autoload.php';
-```
-
-Woah! Now start using monolog! To keep learning more about Composer, keep
-reading the "Basic Usage" chapter.
+Now that you've installed Composer, you are ready to use it! Head on over to the
+next chapter for a short and simple demonstration.
 
-[Basic Usage](01-basic-usage.md) →
+[Basic usage](01-basic-usage.md) →

doc/01-basic-usage.md

@@ -1,8 +1,13 @@
 # Basic usage
 
-## Installing
+## Introduction
 
-If you have not yet installed Composer, refer to the [Intro](00-intro.md) chapter.
+For our basic usage introduction, we will be installing `monolog/monolog`,
+a logging library. If you have not yet installed Composer, refer to the 
+[Intro](00-intro.md) chapter.
+
+> **Note:** for the sake of simplicity, this introduction will assume you
+> have performed a [local](00-intro.md#locally) install of Composer.
 
 ## `composer.json`: Project Setup
 
@@ -10,14 +15,11 @@ To start using Composer in your project, all you need is a `composer.json`
 file. This file describes the dependencies of your project and may contain
 other metadata as well.
 
-The [JSON format](http://json.org/) is quite easy to write. It allows you to
-define nested structures.
-
 ### The `require` Key
 
 The first (and often only) thing you specify in `composer.json` is the
-`require` key. You're simply telling Composer which packages your project
-depends on.
+[`require`](04-schema.md#require) key. You're simply telling Composer which 
+packages your project depends on.
 
 ```json
 {
@@ -27,15 +29,16 @@ depends on.
 }
 ```
 
-As you can see, `require` takes an object that maps **package names** (e.g. `monolog/monolog`)
-to **package versions** (e.g. `1.0.*`).
+As you can see, [`require`](04-schema.md#require) takes an object that maps 
+**package names** (e.g. `monolog/monolog`) to **version constraints** (e.g. 
+`1.0.*`).
 
 ### Package Names
 
 The package name consists of a vendor name and the project's name. Often these
-will be identical - the vendor name just exists to prevent naming clashes. It allows
-two different people to create a library named `json`, which would then just be
-named `igorw/json` and `seldaek/json`.
+will be identical - the vendor name just exists to prevent naming clashes. It
+allows two different people to create a library named `json`, which would then
+just be named `igorw/json` and `seldaek/json`.
 
 Here we are requiring `monolog/monolog`, so the vendor name is the same as the
 project's name. For projects with a unique name this is recommended. It also
@@ -45,89 +48,26 @@ smaller decoupled parts.
 
 ### Package Versions
 
-In the previous example we were requiring version [`1.0.*`](http://semver.mwl.be/#?package=monolog%2Fmonolog&version=1.0.*) of monolog. This
-means any version in the `1.0` development branch. It would match `1.0.0`,
-`1.0.2` or `1.0.20`.
-
-Version constraints can be specified in a few different ways.
-
-Name           | Example                                                                  | Description
--------------- | ------------------------------------------------------------------------ | -----------
-Exact version  | `1.0.2`                                                                  | You can specify the exact version of a package.
-Range          | `>=1.0` `>=1.0 <2.0` <code>&gt;=1.0 &lt;1.1 &#124;&#124; &gt;=1.2</code> | By using comparison operators you can specify ranges of valid versions. Valid operators are `>`, `>=`, `<`, `<=`, `!=`. <br />You can define multiple ranges. Ranges separated by a space (<code> </code>) or comma (`,`) will be treated as a **logical AND**. A double pipe (<code>&#124;&#124;</code>) will be treated as a **logical OR**. AND has higher precedence than OR.
-Hyphen Range   | `1.0 - 2.0`                                                              | Inclusive set of versions. Partial versions on the right include are completed with a wildcard. For example `1.0 - 2.0` is equivalent to `>=1.0.0 <2.1` as the `2.0` becomes `2.0.*`. On the other hand `1.0.0 - 2.1.0` is equivalent to `>=1.0.0 <=2.1.0`.
-Wildcard       | `1.0.*`                                                                  | You can specify a pattern with a `*` wildcard. `1.0.*` is the equivalent of `>=1.0 <1.1`.
-Tilde Operator | `~1.2`                                                                   | Very useful for projects that follow semantic versioning. `~1.2` is equivalent to `>=1.2 <2.0`. For more details, read the next section below.
-Caret Operator | `^1.2.3`                                                                 | Very useful for projects that follow semantic versioning. `^1.2.3` is equivalent to `>=1.2.3 <2.0`. For more details, read the next section below.
-
-### Next Significant Release (Tilde and Caret Operators)
-
-The `~` operator is best explained by example: `~1.2` is equivalent to
-`>=1.2 <2.0.0`, while `~1.2.3` is equivalent to `>=1.2.3 <1.3.0`. As you can see
-it is mostly useful for projects respecting [semantic
-versioning](http://semver.org/). A common usage would be to mark the minimum
-minor version you depend on, like `~1.2` (which allows anything up to, but not
-including, 2.0). Since in theory there should be no backwards compatibility
-breaks until 2.0, that works well. Another way of looking at it is that using
-`~` specifies a minimum version, but allows the last digit specified to go up.
-
-The `^` operator behaves very similarly but it sticks closer to semantic
-versioning, and will always allow non-breaking updates. For example `^1.2.3`
-is equivalent to `>=1.2.3 <2.0.0` as none of the releases until 2.0 should
-break backwards compatibility. For pre-1.0 versions it also acts with safety
-in mind and treats `^0.3` as `>=0.3.0 <0.4.0`
-
-> **Note:** Though `2.0-beta.1` is strictly before `2.0`, a version constraint
-> like `~1.2` would not install it. As said above `~1.2` only means the `.2`
-> can change but the `1.` part is fixed.
-
-> **Note:** The `~` operator has an exception on its behavior for the major
-> release number. This means for example that `~1` is the same as `~1.0` as
-> it will not allow the major number to increase trying to keep backwards
-> compatibility.
+In the previous example we were requiring version
+[`1.0.*`](http://semver.mwl.be/#?package=monolog%2Fmonolog&version=1.0.*) of
+Monolog. This means any version in the `1.0` development branch. It is the
+equivalent of saying versions that match `>=1.0 <1.1`.
+
+Version constraints can be specified in several ways, read 
+[versions](articles/versions.md) for more in-depth information on this topic.
 
 ### Stability
 
-By default only stable releases are taken into consideration. If you would like
-to also get RC, beta, alpha or dev versions of your dependencies you can do
-so using [stability flags](04-schema.md#package-links). To change that for all
-packages instead of doing per dependency you can also use the
+By default only stable releases are taken into consideration. If you would
+like to also get RC, beta, alpha or dev versions of your dependencies you can
+do so using [stability flags](04-schema.md#package-links). To change that for
+all packages instead of doing per dependency you can also use the
 [minimum-stability](04-schema.md#minimum-stability) setting.
 
-If you are using range comparisons when selecting non-stable packages, and you
-specify a numeric version number (that is, no suffix indicating alpha, beta,
-rc, or stable), then both non-stable and stable versions of a particular
-release number will be treated as equally valid.
-
- * `>=`/`<=` will accept non-stable releases as well as the stable release.
- * `<`/`>` will reject non-stable releasese as well as the stable release.
-
-If you wish to consider only the stable release in the comparison, add the
-suffix `-stable` to the version number.
-
-Here are some examples:
-
- Example         | Interpretation
- --------------- | --------------
-`>=1.0.0`        | Any release, stable or non-, of 1.0.0 will be allowed
-`>=1.0.0-stable` | Only the stable release of 1.0.0 will be allowed
-`<2.0.0`         | Neither release, stable or non-, of 2.0.0 will be allowed
-`<2.0.0-stable`  | Only the stable release of 2.0.0 will be disallowed; non-stable releases will be allowed
-
-Note that the packages matched by these constraints are still checked against
-the `minimum-stability` setting and each package's stability flags.
-
-### Test version constraints
-
-You can test version constraints using [semver.mwl.be](http://semver.mwl.be). Fill in
-a package name and it will autofill the default version constraint which Composer would add
-to your `composer.json` file. You can adjust the version constraint and the tool will highlight
-all releases that match.
-
 ## Installing Dependencies
 
-To fetch the defined dependencies into your local project, just run the
-`install` command of `composer.phar`.
+To install the defined dependencies for your project, just run the
+[`install`](03-cli.md#install) command.
 
 ```sh
 php composer.phar install
@@ -136,14 +76,14 @@ php composer.phar install
 This will find the latest version of `monolog/monolog` that matches the
 supplied version constraint and download it into the `vendor` directory.
 It's a convention to put third party code into a directory named `vendor`.
-In case of monolog it will put it into `vendor/monolog/monolog`.
+In case of Monolog it will put it into `vendor/monolog/monolog`.
 
 > **Tip:** If you are using git for your project, you probably want to add
-> `vendor` into your `.gitignore`. You really don't want to add all of that
+> `vendor` in your `.gitignore`. You really don't want to add all of that
 > code to your repository.
 
-Another thing that the `install` command does is it adds a `composer.lock`
-file into your project root.
+You will notice the [`install`](03-cli.md#install) command also created a 
+`composer.lock` file.
 
 ## `composer.lock` - The Lock File
 
@@ -151,82 +91,82 @@ After installing the dependencies, Composer writes the list of the exact
 versions it installed into a `composer.lock` file. This locks the project
 to those specific versions.
 
-**Commit your application's `composer.lock` (along with `composer.json`) into version control.**
+**Commit your application's `composer.lock` (along with `composer.json`)
+into version control.**
 
-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 is important because the [`install`](03-cli.md#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. 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.
+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 after executing the `update` or the `install`
-command.
+versions from `composer.json` and  create the lock file after executing the
+[`update`](03-cli.md#update) or the [`install`](03-cli.md#install) command.
 
-This means that if any of the dependencies get a new version, you won't get the updates
-automatically. To update to the new version, use the `update` command. This will fetch
-the latest matching versions (according to your `composer.json` file) and also update
-the lock file with the new version.
+This means that if any of the dependencies get a new version, you won't get the
+updates automatically. To update to the new version, use the 
+[`update`](03-cli.md#update) command. This will fetch the latest matching 
+versions (according to your `composer.json` file) and also update the lock file 
+with the new version.
 
 ```sh
 php composer.phar update
 ```
-> **Note:** Composer will display a Warning when executing an `install` command if 
- `composer.lock` and `composer.json` are not synchronized.
- 
+> **Note:** Composer will display a Warning when executing an `install` command
+> if `composer.lock` and `composer.json` are not synchronized.
+
 If you only want to install or update one dependency, you can whitelist them:
 
 ```sh
 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).
+> **Note:** For libraries it is not necessary to commit the lock
+> file, see also: [Libraries - Lock file](02-libraries.md#lock-file).
 
 ## Packagist
 
 [Packagist](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.
+means that you can automatically `require` any package that is available there.
 
-If you go to the [packagist website](https://packagist.org/) (packagist.org),
+If you go to the [Packagist website](https://packagist.org/) (packagist.org),
 you can browse and search for packages.
 
-Any open source project using Composer should publish their packages on
-packagist. A library doesn't need to be on packagist to be used by Composer,
-but it makes life quite a bit simpler.
+Any open source project using Composer is recommended to publish their packages 
+on Packagist. A library doesn't need to be on Packagist to be used by Composer, 
+but it enables discovery and adoption by other developers more quickly.
 
 ## Autoloading
 
 For libraries that specify autoload information, Composer generates a
-`vendor/autoload.php` file. You can simply include this file and you
-will get autoloading for free.
+`vendor/autoload.php` file. You can simply include this file and you will get
+autoloading for free.
 
 ```php
 require 'vendor/autoload.php';
 ```
 
-This makes it really easy to use third party code. For example: If your
-project depends on monolog, you can just start using classes from it, and they
-will be autoloaded.
+This makes it really easy to use third party code. For example: If your project
+depends on Monolog, you can just start using classes from it, and they will be
+autoloaded.
 
 ```php
 $log = new Monolog\Logger('name');
 $log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
-
 $log->addWarning('Foo');
 ```
 
-You can even add your own code to the autoloader by adding an `autoload` field
-to `composer.json`.
+You can even add your own code to the autoloader by adding an 
+[`autoload`](04-schema.md#autoload) field to `composer.json`.
 
 ```json
 {
@@ -243,8 +183,9 @@ You define a mapping from namespaces to directories. The `src` directory would
 be in your project root, on the same level as `vendor` directory is. An example
 filename would be `src/Foo.php` containing an `Acme\Foo` class.
 
-After adding the `autoload` field, you have to re-run `dump-autoload` to re-generate
-the `vendor/autoload.php` file.
+After adding the [`autoload`](04-schema.md#autoload) field, you have to re-run 
+[`dump-autoload`](03-cli.md#dump-autoload) to re-generate the 
+`vendor/autoload.php` file.
 
 Including that file will also return the autoloader instance, so you can store
 the return value of the include call in a variable and add more namespaces.
@@ -255,12 +196,12 @@ $loader = require 'vendor/autoload.php';
 $loader->add('Acme\\Test\\', __DIR__);
 ```
 
-In addition to PSR-4 autoloading, classmap is also supported. This allows
-classes to be autoloaded even if they do not conform to PSR-4. See the
-[autoload reference](04-schema.md#autoload) for more details.
+In addition to PSR-4 autoloading, Composer also supports PSR-0, classmap and 
+files autoloading. See the [`autoload`](04-schema.md#autoload) reference for 
+more information.
 
-> **Note:** Composer provides its own autoloader. If you don't want to use
-that one, you can just include `vendor/composer/autoload_*.php` files,
-which return associative arrays allowing you to configure your own autoloader.
+> **Note:** Composer provides its own autoloader. If you don't want to use that
+> one, you can just include `vendor/composer/autoload_*.php` files, which return
+> associative arrays allowing you to configure your own autoloader.
 
 &larr; [Intro](00-intro.md)  |  [Libraries](02-libraries.md) &rarr;

doc/02-libraries.md

@@ -1,16 +1,17 @@
 # Libraries
 
-This chapter will tell you how to make your library installable through Composer.
+This chapter will tell you how to make your library installable through
+Composer.
 
 ## Every project is a package
 
 As soon as you have a `composer.json` in a directory, that directory is a
-package. When you add a `require` to a project, you are making a package that
-depends on other packages. The only difference between your project and
-libraries is that your project is a package without a name.
+package. When you add a [`require`](04-schema.md#require) to a project, you are
+making a package that depends on other packages. The only difference between
+your project and libraries is that your project is a package without a name.
 
 In order to make that package installable you need to give it a name. You do
-this by adding a `name` to `composer.json`:
+this by adding the [`name`](04-schema.md#name) property in `composer.json`:
 
 ```json
 {
@@ -21,12 +22,12 @@ this by adding a `name` to `composer.json`:
 }
 ```
 
-In this case the project name is `acme/hello-world`, where `acme` is the
-vendor name. Supplying a vendor name is mandatory.
+In this case the project name is `acme/hello-world`, where `acme` is the vendor
+name. Supplying a vendor name is mandatory.
 
 > **Note:** If you don't know what to use as a vendor name, your GitHub
-username is usually a good bet. While package names are case insensitive, the
-convention is all lowercase and dashes for word separation.
+> username is usually a good bet. While package names are case insensitive, the
+> convention is all lowercase and dashes for word separation.
 
 ## Platform packages
 
@@ -50,15 +51,14 @@ includes PHP itself, PHP extensions and some system libraries.
   PHP. The following are available: `curl`, `iconv`, `icu`, `libxml`,
   `openssl`, `pcre`, `uuid`, `xsl`.
 
-You can use `composer show --platform` to get a list of your locally available
-platform packages.
+You can use [`show --platform`](03-cli.md#show) to get a list of your locally
+available platform packages.
 
 ## Specifying the version
 
-You need to specify the package's version some way. When you publish your
-package on Packagist, it is able to infer the version from the VCS (git, svn,
-hg) information, so in that case you do not have to specify it, and it is
-recommended not to. See [tags](#tags) and [branches](#branches) to see how
+When you publish your package on Packagist, it is able to infer the version
+from the VCS (git, svn, hg) information. This means you don't have to
+explicitly declare it. Read [tags](#tags) and [branches](#branches) to see how
 version numbers are extracted from these.
 
 If you are creating packages by hand and really have to specify it explicitly,
@@ -76,9 +76,9 @@ you can just add a `version` field:
 ### Tags
 
 For every tag that looks like a version, a package version of that tag will be
-created. It should match 'X.Y.Z' or 'vX.Y.Z', with an optional suffix
-of `-patch` (`-p`), `-alpha` (`-a`), `-beta` (`-b`) or `-RC`. The suffixes
-can also be followed by a number.
+created. It should match 'X.Y.Z' or 'vX.Y.Z', with an optional suffix of
+`-patch` (`-p`), `-alpha` (`-a`), `-beta` (`-b`) or `-RC`. The suffix can also
+be followed by a number.
 
 Here are a few examples of valid tag names:
 
@@ -89,19 +89,20 @@ Here are a few examples of valid tag names:
 - v2.0.0-alpha
 - v2.0.4-p1
 
-> **Note:** Even if your tag is prefixed with `v`, a [version constraint](01-basic-usage.md#package-versions)
-> in a `require` statement has to be specified without prefix
-> (e.g. tag `v1.0.0` will result in version `1.0.0`). 
+> **Note:** Even if your tag is prefixed with `v`, a
+> [version constraint](01-basic-usage.md#package-versions) in a `require`
+> statement has to be specified without prefix (e.g. tag `v1.0.0` will result
+> in version `1.0.0`).
 
 ### Branches
 
 For every branch, a package development version will be created. If the branch
 name looks like a version, the version will be `{branchname}-dev`. For example,
-the branch `2.0` will get the `2.0.x-dev` version (the `.x` is added for technical
-reasons, to make sure it is recognized as a branch). The `2.0.x` branch would also
-be valid and be turned into `2.0.x-dev` as well. If the branch does not look
-like a version, it will be `dev-{branchname}`. `master` results in a
-`dev-master` version.
+the branch `2.0` will get the `2.0.x-dev` version (the `.x` is added for
+technical reasons, to make sure it is recognized as a branch). The `2.0.x`
+branch would also be valid and be turned into `2.0.x-dev` as well. If the
+branch does not look like a version, it will be `dev-{branchname}`. `master`
+results in a `dev-master` version.
 
 Here are some examples of version branch names:
 
@@ -116,8 +117,8 @@ Here are some examples of version branch names:
 ### Aliases
 
 It is possible to alias branch names to versions. For example, you could alias
-`dev-master` to `1.0.x-dev`, which would allow you to require `1.0.x-dev` in all
-the packages.
+`dev-master` to `1.0.x-dev`, which would allow you to require `1.0.x-dev` in
+all the packages.
 
 See [Aliases](articles/aliases.md) for more information.
 
@@ -133,7 +134,7 @@ the `.gitignore`.
 
 ## Publishing to a VCS
 
-Once you have a vcs repository (version control system, e.g. git) containing a
+Once you have a VCS repository (version control system, e.g. git) containing a
 `composer.json` file, your library is already composer-installable. In this
 example we will publish the `acme/hello-world` library on GitHub under
 `github.com/username/hello-world`.
@@ -180,11 +181,11 @@ For more details on how package repositories work and what other types are
 available, see [Repositories](05-repositories.md).
 
 That's all. You can now install the dependencies by running Composer's
-`install` command!
+[`install`](03-cli.md#install) command!
 
 **Recap:** Any git/svn/hg repository containing a `composer.json` can be added
 to your project by specifying the package repository and declaring the
-dependency in the `require` field.
+dependency in the [`require`](04-schema.md#require) field.
 
 ## Publishing to packagist
 
@@ -196,15 +197,16 @@ repository for `monolog/monolog`. How did that work? The answer is Packagist.
 
 [Packagist](https://packagist.org/) is the main package repository for
 Composer, and it is enabled by default. Anything that is published on
-Packagist is available automatically through Composer. Since monolog
-[is on packagist](https://packagist.org/packages/monolog/monolog), we can depend
-on it without having to specify any additional repositories.
+Packagist is available automatically through Composer. Since
+[Monolog is on Packagist](https://packagist.org/packages/monolog/monolog), we
+can depend on it without having to specify any additional repositories.
 
 If we wanted to share `hello-world` with the world, we would publish it on
 Packagist as well. Doing so is really easy.
 
-You simply hit the big "Submit Package" button and sign up. Then you submit
-the URL to your VCS repository, at which point Packagist will start crawling
-it. Once it is done, your package will be available to anyone.
+You simply visit [Packagist](https://packagist.org) and hit the "Submit". This
+will prompt you to sign up if you haven't already, and then allows you to
+submit the URL to your VCS repository, at which point Packagist will start
+crawling it. Once it is done, your package will be available to anyone!
 
 ← [Basic usage](01-basic-usage.md) |  [Command-line interface](03-cli.md) →

doc/06-config.md

@@ -46,6 +46,11 @@ A list of domain names and username/passwords to authenticate against them. For
 example using `{"example.org": {"username": "alice", "password": "foo"}` as the
 value of this option will let Composer authenticate against example.org.
 
+> **Note:** Authentication-related config options like `http-basic` and
+> `github-oauth` can also be specified inside a `auth.json` file that goes
+> besides your `composer.json`. That way you can gitignore it and every
+> developer can place their own credentials in there.
+
 ## platform
 
 Lets you fake platform packages (PHP and extensions) so that you can emulate a
@@ -99,7 +104,7 @@ first until the cache fits.
 
 ## prepend-autoloader
 
-Defaults to `true`. If false, the Composer autoloader will not be prepended to
+Defaults to `true`. If `false`, the Composer autoloader will not be prepended to
 existing autoloaders. This is sometimes required to fix interoperability issues
 with other autoloaders.
 
@@ -110,7 +115,7 @@ autoloader. When null a random one will be generated.
 
 ## optimize-autoloader
 
-Defaults to `false`. Always optimize when dumping the autoloader.
+Defaults to `false`. If `true`, always optimize when dumping the autoloader.
 
 ## classmap-authoritative
 
@@ -125,7 +130,7 @@ used for GitHub Enterprise setups.
 
 ## github-expose-hostname
 
-Defaults to `true`. If set to `false`, the OAuth tokens created to access the
+Defaults to `true`. If `false`, the OAuth tokens created to access the
 github API will have a date instead of the machine hostname.
 
 ## notify-on-install
@@ -163,9 +168,4 @@ Example:
 }
 ```
 
-> **Note:** Authentication-related config options like `http-basic` and
-> `github-oauth` can also be specified inside a `auth.json` file that goes
-> besides your `composer.json`. That way you can gitignore it and every
-> developer can place their own credentials in there.
-
 ← [Repositories](05-repositories.md)  |  [Community](07-community.md) →

doc/articles/versions.md

@@ -0,0 +1,112 @@
+<!--
+    tagline: The multitude of possibilities that are called version constraints.
+-->
+
+# Versions
+
+## Basic Constraints
+
+### Exact
+
+You can specify the exact version of a package. This will tell Composer to
+install this version and this version only. If other dependencies require
+a different version, the solver will ultimately fail and abort any install
+or update procedures.
+
+Example: `1.0.2`
+
+### Range
+
+By using comparison operators you can specify ranges of valid versions. Valid
+operators are `>`, `>=`, `<`, `<=`, `!=`.
+
+You can define multiple ranges. Ranges separated by a space (` `) or comma (`,`)
+will be treated as a **logical AND**. A double pipe (`||`) will be treated as a
+**logical OR**. AND has higher precedence than OR.
+
+Examples:
+
+* `>=1.0`
+* `>=1.0 <2.0`
+* `>=1.0 <1.1 || >=1.2`
+
+### Range (Hyphen)
+
+Inclusive set of versions. Partial versions on the right include are completed
+with a wildcard. For example `1.0 - 2.0` is equivalent to `>=1.0.0 <2.1` as the
+`2.0` becomes `2.0.*`. On the other hand `1.0.0 - 2.1.0` is equivalent to
+`>=1.0.0 <=2.1.0`.
+
+Example: `1.0 - 2.0`
+
+### Wildcard
+
+You can specify a pattern with a `*` wildcard. `1.0.*` is the equivalent of
+`>=1.0 <1.1`.
+
+Example: `1.0.*`
+
+## Next Significant Release Operators
+
+### Tilde
+
+The `~` operator is best explained by example: `~1.2` is equivalent to
+`>=1.2 <2.0.0`, while `~1.2.3` is equivalent to `>=1.2.3 <1.3.0`. As you can see
+it is mostly useful for projects respecting [semantic
+versioning](http://semver.org/). A common usage would be to mark the minimum
+minor version you depend on, like `~1.2` (which allows anything up to, but not
+including, 2.0). Since in theory there should be no backwards compatibility
+breaks until 2.0, that works well. Another way of looking at it is that using
+`~` specifies a minimum version, but allows the last digit specified to go up.
+
+Example: `~1.2`
+
+> **Note:** Though `2.0-beta.1` is strictly before `2.0`, a version constraint
+> like `~1.2` would not install it. As said above `~1.2` only means the `.2`
+> can change but the `1.` part is fixed.
+
+> **Note:** The `~` operator has an exception on its behavior for the major
+> release number. This means for example that `~1` is the same as `~1.0` as
+> it will not allow the major number to increase trying to keep backwards
+> compatibility.
+
+### Caret
+
+The `^` operator behaves very similarly but it sticks closer to semantic
+versioning, and will always allow non-breaking updates. For example `^1.2.3`
+is equivalent to `>=1.2.3 <2.0.0` as none of the releases until 2.0 should
+break backwards compatibility. For pre-1.0 versions it also acts with safety
+in mind and treats `^0.3` as `>=0.3.0 <0.4.0`.
+
+Example: `^1.2.3`
+
+## Stability
+
+If you are using a constraint that does not explicitly define a stability,
+Composer will default interally to `-dev` or `-stable`, depending on the
+operator(s) used. This happens transparently.
+
+If you wish to explicitly consider only the stable release in the comparison,
+add the suffix `-stable`.
+
+Examples:
+
+ Constraint         | Internally
+----------------------------------------------
+ `1.2.3`            | `=1.2.3.0-stable`
+ `>1.2`             | `>1.2.0.0-stable`
+ `>=1.2`            | `>=1.2.0.0-dev`
+ `>=1.2-stable`     | `>=1.2.0.0-stable`
+ `<1.3`             | `<1.3.0.0-dev`
+ `<=1.3`            | `<=1.3.0.0-stable`
+ `1 - 2`            | `>=1.0.0.0-dev <3.0.0.0-dev`
+ `~1.3`             | `>=1.3.0.0-dev <2.0.0.0-dev`
+ `1.4.*`            | `>=1.4.0.0-dev <1.5.0.0-dev`
+
+## Test version constraints
+
+You can test version constraints using [semver.mwl.be](http://semver.mwl.be).
+Fill in a package name and it will autofill the default version constraint
+which Composer would add to your `composer.json` file. You can adjust the
+version constraint and the tool will highlight all releases that match.
+