Procházet zdrojové kódy

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

Jordi Boggiano před 9 roky
rodič
revize
720a25abb9
5 změnil soubory, kde provedl 303 přidání a 267 odebrání
  1. 67 86
      doc/00-intro.md
  2. 77 136
      doc/01-basic-usage.md
  3. 39 37
      doc/02-libraries.md
  4. 8 8
      doc/06-config.md
  5. 112 0
      doc/articles/versions.md

+ 67 - 86
doc/00-intro.md

@@ -1,54 +1,41 @@
 # Introduction
 # Introduction
 
 
 Composer is a tool for dependency management in PHP. It allows you to declare
 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
 ## 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.
 a) You have a project that depends on a number of libraries.
 
 
 b) Some of those libraries depend on other 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
 ## System Requirements
 
 
 Composer requires PHP 5.3.2+ to run. A few sensitive php settings and compile
 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
 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.
 git, svn or hg depending on how the package is version-controlled.
@@ -60,6 +47,12 @@ Linux and OSX.
 
 
 ### Downloading the Composer Executable
 ### 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
 There are in short, two ways to install Composer. Locally as part of your
 project, or globally as a system wide executable.
 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
 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`
 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
 ```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
 #### 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
 ```sh
 curl -sS https://getcomposer.org/installer | php
 curl -sS https://getcomposer.org/installer | php
 mv composer.phar /usr/local/bin/composer
 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
 ## 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.
 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
 ### Manual Installation
 
 
 Change to a directory on your `PATH` and run the install snippet to download
 Change to a directory on your `PATH` and run the install snippet to download
-composer.phar:
+`composer.phar`:
 
 
 ```sh
 ```sh
 C:\Users\username>cd C:\bin
 C:\Users\username>cd C:\bin
 C:\bin>php -r "readfile('https://getcomposer.org/installer');" | php
 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`:
 Create a new `composer.bat` file alongside `composer.phar`:
 
 
@@ -153,38 +165,7 @@ Composer version 27d8904
 
 
 ## Using Composer
 ## 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) →

+ 77 - 136
doc/01-basic-usage.md

@@ -1,8 +1,13 @@
 # Basic usage
 # 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
 ## `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
 file. This file describes the dependencies of your project and may contain
 other metadata as well.
 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 `require` Key
 
 
 The first (and often only) thing you specify in `composer.json` is the
 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
 ```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
 ### Package Names
 
 
 The package name consists of a vendor name and the project's name. Often these
 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
 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
 project's name. For projects with a unique name this is recommended. It also
@@ -45,89 +48,26 @@ smaller decoupled parts.
 
 
 ### Package Versions
 ### 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
 ### 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.
 [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
 ## 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
 ```sh
 php composer.phar install
 php composer.phar install
@@ -136,14 +76,14 @@ php composer.phar install
 This will find the latest version of `monolog/monolog` that matches the
 This will find the latest version of `monolog/monolog` that matches the
 supplied version constraint and download it into the `vendor` directory.
 supplied version constraint and download it into the `vendor` directory.
 It's a convention to put third party code into a directory named `vendor`.
 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
 > **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.
 > 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
 ## `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
 versions it installed into a `composer.lock` file. This locks the project
 to those specific versions.
 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
 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
 ```sh
 php composer.phar update
 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:
 If you only want to install or update one dependency, you can whitelist them:
 
 
 ```sh
 ```sh
 php composer.phar update monolog/monolog [...]
 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
 
 
 [Packagist](https://packagist.org/) is the main Composer repository. A Composer
 [Packagist](https://packagist.org/) is the main Composer repository. A Composer
 repository is basically a package source: a place where you can get packages
 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
 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.
 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
 ## Autoloading
 
 
 For libraries that specify autoload information, Composer generates a
 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
 ```php
 require 'vendor/autoload.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
 ```php
 $log = new Monolog\Logger('name');
 $log = new Monolog\Logger('name');
 $log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
 $log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
-
 $log->addWarning('Foo');
 $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
 ```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
 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.
 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
 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.
 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__);
 $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;
 &larr; [Intro](00-intro.md)  |  [Libraries](02-libraries.md) &rarr;

+ 39 - 37
doc/02-libraries.md

@@ -1,16 +1,17 @@
 # Libraries
 # 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
 ## Every project is a package
 
 
 As soon as you have a `composer.json` in a directory, that directory is a
 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
 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
 ```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
 > **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
 ## Platform packages
 
 
@@ -50,15 +51,14 @@ includes PHP itself, PHP extensions and some system libraries.
   PHP. The following are available: `curl`, `iconv`, `icu`, `libxml`,
   PHP. The following are available: `curl`, `iconv`, `icu`, `libxml`,
   `openssl`, `pcre`, `uuid`, `xsl`.
   `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
 ## 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.
 version numbers are extracted from these.
 
 
 If you are creating packages by hand and really have to specify it explicitly,
 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
 ### Tags
 
 
 For every tag that looks like a version, a package version of that tag will be
 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:
 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.0-alpha
 - v2.0.4-p1
 - 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
 ### Branches
 
 
 For every branch, a package development version will be created. If the branch
 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,
 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:
 Here are some examples of version branch names:
 
 
@@ -116,8 +117,8 @@ Here are some examples of version branch names:
 ### Aliases
 ### Aliases
 
 
 It is possible to alias branch names to versions. For example, you could alias
 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.
 See [Aliases](articles/aliases.md) for more information.
 
 
@@ -133,7 +134,7 @@ the `.gitignore`.
 
 
 ## Publishing to a VCS
 ## 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
 `composer.json` file, your library is already composer-installable. In this
 example we will publish the `acme/hello-world` library on GitHub under
 example we will publish the `acme/hello-world` library on GitHub under
 `github.com/username/hello-world`.
 `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).
 available, see [Repositories](05-repositories.md).
 
 
 That's all. You can now install the dependencies by running Composer's
 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
 **Recap:** Any git/svn/hg repository containing a `composer.json` can be added
 to your project by specifying the package repository and declaring the
 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
 ## 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
 [Packagist](https://packagist.org/) is the main package repository for
 Composer, and it is enabled by default. Anything that is published on
 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
 If we wanted to share `hello-world` with the world, we would publish it on
 Packagist as well. Doing so is really easy.
 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!
 
 
 &larr; [Basic usage](01-basic-usage.md) |  [Command-line interface](03-cli.md) &rarr;
 &larr; [Basic usage](01-basic-usage.md) |  [Command-line interface](03-cli.md) &rarr;

+ 8 - 8
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
 example using `{"example.org": {"username": "alice", "password": "foo"}` as the
 value of this option will let Composer authenticate against example.org.
 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
 ## platform
 
 
 Lets you fake platform packages (PHP and extensions) so that you can emulate a
 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
 ## 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
 existing autoloaders. This is sometimes required to fix interoperability issues
 with other autoloaders.
 with other autoloaders.
 
 
@@ -110,7 +115,7 @@ autoloader. When null a random one will be generated.
 
 
 ## optimize-autoloader
 ## optimize-autoloader
 
 
-Defaults to `false`. Always optimize when dumping the autoloader.
+Defaults to `false`. If `true`, always optimize when dumping the autoloader.
 
 
 ## classmap-authoritative
 ## classmap-authoritative
 
 
@@ -125,7 +130,7 @@ used for GitHub Enterprise setups.
 
 
 ## github-expose-hostname
 ## 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.
 github API will have a date instead of the machine hostname.
 
 
 ## notify-on-install
 ## 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.
-
 &larr; [Repositories](05-repositories.md)  |  [Community](07-community.md) &rarr;
 &larr; [Repositories](05-repositories.md)  |  [Community](07-community.md) &rarr;

+ 112 - 0
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.
+