diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md
index d52a7d735..83bb68e25 100644
--- a/doc/01-basic-usage.md
+++ b/doc/01-basic-usage.md
@@ -2,11 +2,12 @@
## 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. Note that for the sake of simplicity,
-this introduction will assume you have performed a [local](00-intro.md#locally)
-install of Composer.
+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
@@ -62,36 +63,6 @@ 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 install the defined dependencies for your project, just run the
diff --git a/doc/articles/versions.md b/doc/articles/versions.md
index eae9da9be..b59e5e70e 100644
--- a/doc/articles/versions.md
+++ b/doc/articles/versions.md
@@ -8,7 +8,7 @@
### Exact
-You can specify the exact version of a package. This will tell Composer to
+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.
@@ -17,26 +17,32 @@ 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.
+By using comparison operators you can specify ranges of valid versions. Valid
+operators are `>`, `>=`, `<`, `<=`, `!=`.
-Example: `>=1.0` `>=1.0 <2.0` `>=1.0 <1.1 || >=1.2`
+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
+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
+You can specify a pattern with a `*` wildcard. `1.0.*` is the equivalent of
`>=1.0 <1.1`.
Example: `1.0.*`
@@ -97,3 +103,11 @@ Examples:
`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.
+