From 7a9f24b913cbdb7cb4bd81cb1f57b2e385200f8d Mon Sep 17 00:00:00 2001 From: Kael Shipman Date: Thu, 19 Jan 2017 19:04:24 -0600 Subject: [PATCH 01/15] Added some useful overview information about repositories in the Basic Usage documentation. --- doc/01-basic-usage.md | 68 +++++++++++++++++++++++++++---------------- 1 file changed, 43 insertions(+), 25 deletions(-) diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index b33f06ac6..9515d8a35 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -33,18 +33,21 @@ 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.*`). +It uses this information to search for the right set of files in package +"repositories" that you register using the [`repositories`](04-schema.md#repositories) +key, or in Packagist, the default package respository. In the above example, +since no other repository is registered in the file, it is assumed that the +`monolog/monolog` package is registered on Packagist. (See more about Packagist +[below](#packagist), or read more about repositories [here](05-repositories.md). + ### 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. For +example, it would allow two different people to create a library named `json`. +One might be named `igorw/json` while the other might be `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 -allows adding more related projects under the same namespace later on. If you -are maintaining a library, this would make it really easy to split it up into -smaller decoupled parts. +Read more about publishing packages and package naming [here](02-libraries.md) ### Package Versions @@ -53,16 +56,30 @@ In the previous example we were requiring version 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 +Version constraints can be specified in several ways; please read [versions](articles/versions.md) for more in-depth information on this topic. -### Stability +> **How does Composer download the right files?** When you specify a dependency in +> `composer.json`, Composer, first takes the name of the package that you've requested +> and searches for it in any repositories that you've registered using the +> [`repositories`](04-schema.md#repositories) key. If you haven't registered +> any extra repositories, or it doesn't find a package with that name in the +> repositories you've specified, it falls back to Packagist (more [below](#packagist)). +> +> When it finds the right package, either in Packagist or in a repo you've specified, +> it then uses the versioning features of the package's VCS to attempt to find the +> best match for the version you've specified. Read more on package resolution +> [here](articles/versions.md). -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. +> **Note:** If you're trying to require a package but Composer throws an error +> regarding package stability, the version you've specified may not meet the +> default minimum stability requirements that Composer establishes. By default +> only stable releases are taken into consideration when searching for package +> versions in your VCS. +> +> You might run into this if you're trying to require dev, alpha, beta, or RC +> versions of a package. Read more about stability flags and the `minimum-stability` +> key on the [schema page](04-schema.md). ## Installing Dependencies @@ -76,7 +93,7 @@ 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 the 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` in your `.gitignore`. You really don't want to add all of that @@ -99,16 +116,16 @@ 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. +versions of the dependencies that you're using. Your CI server, production +machines, other developers in your team, everything and everyone runs on the +same dependencies, which mitigates the potential for bugs affecting only some +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. +(See note below about using the `update` command.) 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`](03-cli.md#update) or the [`install`](03-cli.md#install) command. +versions from `composer.json` and create the lock file after executing. 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 @@ -136,7 +153,8 @@ php composer.phar update monolog/monolog [...] [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, +without further specifying where Composer should look for the package. If you go to the [Packagist website](https://packagist.org/) (packagist.org), you can browse and search for packages. From a0d293494613ce10eb306e5ced6d9bc3961225b5 Mon Sep 17 00:00:00 2001 From: Kael Shipman Date: Fri, 20 Jan 2017 11:49:29 -0600 Subject: [PATCH 02/15] Updated basic usage and versions pages to clarify how versioning and package resolution works (refs #6088) --- doc/01-basic-usage.md | 101 +++++++++++++++++++++------------------ doc/articles/versions.md | 101 +++++++++++++++++++++++++++++++++++++-- 2 files changed, 150 insertions(+), 52 deletions(-) diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index 9515d8a35..3aea1a1ed 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -36,9 +36,10 @@ As you can see, [`require`](04-schema.md#require) takes an object that maps It uses this information to search for the right set of files in package "repositories" that you register using the [`repositories`](04-schema.md#repositories) key, or in Packagist, the default package respository. In the above example, -since no other repository is registered in the file, it is assumed that the -`monolog/monolog` package is registered on Packagist. (See more about Packagist -[below](#packagist), or read more about repositories [here](05-repositories.md). +since no other repository has been registered in the `composer.json` file, it is +assumed that the `monolog/monolog` package is registered on Packagist. (See more +about Packagist [below](#packagist), or read more about repositories +[here](05-repositories.md). ### Package Names @@ -49,15 +50,15 @@ One might be named `igorw/json` while the other might be `seldaek/json`. Read more about publishing packages and package naming [here](02-libraries.md) -### Package Versions +### Package Version Constraints -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`. +In our example, we're requesting the Monolog package with the version constraint +[`1.0.*`](http://semver.mwl.be/#?package=monolog%2Fmonolog&version=1.0.*). +This means any version in the `1.0` development branch, or any version that is +greater than or equal to 1.0 and less than 1.1 (`>=1.0 <1.1`). -Version constraints can be specified in several ways; please read -[versions](articles/versions.md) for more in-depth information on this topic. +Version can be a little confusing in Composer, and version constraints can be specified +in several ways. Please read [versions](articles/versions.md) for more in-depth information. > **How does Composer download the right files?** When you specify a dependency in > `composer.json`, Composer, first takes the name of the package that you've requested @@ -67,15 +68,14 @@ Version constraints can be specified in several ways; please read > repositories you've specified, it falls back to Packagist (more [below](#packagist)). > > When it finds the right package, either in Packagist or in a repo you've specified, -> it then uses the versioning features of the package's VCS to attempt to find the -> best match for the version you've specified. Read more on package resolution -> [here](articles/versions.md). +> it then uses the versioning features of the package's VCS (i.e., branches and tags) +> to attempt to find the best match for the version you've specified. Be sure to read +> about versions and package resolution in the [versions article](articles/versions.md). > **Note:** If you're trying to require a package but Composer throws an error -> regarding package stability, the version you've specified may not meet the -> default minimum stability requirements that Composer establishes. By default -> only stable releases are taken into consideration when searching for package -> versions in your VCS. +> regarding package stability, the version you've specified may not meet your +> default minimum stability requirements. By default only stable releases are taken +> into consideration when searching for valid package versions in your VCS. > > You might run into this if you're trying to require dev, alpha, beta, or RC > versions of a package. Read more about stability flags and the `minimum-stability` @@ -90,32 +90,46 @@ To install the defined dependencies for your project, just run the 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 the case of Monolog it will put it into `vendor/monolog/monolog`. +When you run this command, one of two things may happen: + +### Installing Without `composer.lock` + +If you've never run the command before and there is also no `composer.lock` file present, +Composer simply resolves all dependencies listed in your `composer.json` file and downloads +the latest version of their files into the `vendor` directory in your project. (The `vendor` +directory is the conventional location for all third-party code in a project). In our +example from above, you would end up with the Monolog source files in +`vendor/monolog/monolog/`. If Monolog listed any dependencies, those would also be in +folders under `vendor/`. > **Tip:** If you are using git for your project, you probably want to add > `vendor` in your `.gitignore`. You really don't want to add all of that -> code to your repository. +> third-party code to your versioned repository. -You will notice the [`install`](03-cli.md#install) command also created a -`composer.lock` file. +When Composer has finished installing, it writes all of the packages and the exact versions +of them that it downloaded to the `composer.lock` file, locking the project to those specific +versions. -## `composer.lock` - The Lock File +### Installing With `composer.lock` -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. +This brings us to the second scenario. If there's already a `composer.lock` file as well as a +`composer.json` file when you run `composer install`, it means that either you've run the +`install` command before, or someone else on the project has run the `install` command and +committed the `composer.lock` file to the project (which is good). -**Commit your application's `composer.lock` (along with `composer.json`) -into version control.** +Either way, running `install` when a `composer.lock` file is present simply resolves and installs +all dependencies that you've listed in `composer.json`, but it uses the version constraints +that it finds in `composer.lock` to ensure that the package versions are consistent for everyone +working on your project. The result is that you have all dependencies requested by your +`composer.json` file, but that they may not all be at the very latest available versions (since +some of the dependencies listed in the `composer.lock` file may have released new versions since +the file was created). This is by design, as it ensures that your project never breaks because of +unexpected changes in dependencies. -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). +### Commit Your `composer.lock` File to Version Control -This means that anyone who sets up the project will download the exact same +Committing this file to VC is important because it will cause anyone who sets +up the project to use the exact same versions of the dependencies that you're using. Your CI server, production machines, other developers in your team, everything and everyone runs on the same dependencies, which mitigates the potential for bugs affecting only some @@ -124,14 +138,13 @@ reinstalling the project you can feel confident the dependencies installed are still working even if your dependencies released many new versions since then. (See note below about using the `update` command.) -If no `composer.lock` file exists, Composer will read the dependencies and -versions from `composer.json` and create the lock file after executing. +## Updating Dependencies to their Latest Versions -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 +As mentioned above, the `composer.lock` file prevents you from automatically getting +the latest versions of your dependencies. To update to the latest versions, use the [`update`](03-cli.md#update) command. This will fetch the latest matching versions (according to your `composer.json` file) and also update the lock file -with the new version. +with the new version. (This is equivalent to simply deleting the `composer.lock` file.) ```sh php composer.phar update @@ -166,18 +179,12 @@ 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 start +using the classes that those libraries provide without any extra work: ```php require __DIR__ . '/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. - -```php $log = new Monolog\Logger('name'); $log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING)); $log->addWarning('Foo'); diff --git a/doc/articles/versions.md b/doc/articles/versions.md index 5557667c9..3322361c4 100644 --- a/doc/articles/versions.md +++ b/doc/articles/versions.md @@ -1,10 +1,100 @@ # Versions -## Basic Constraints +## Composer Versions vs VCS Versions + +Because Composer is heavily geared toward utilizing version control systems +like git, the term "version" can be a little ambiguous. In the sense of a +version control system, a "version" is a specific set of files that contain +specific data. In git terminology, this is a "ref", or a specific commit, +which may be represented by a branch HEAD or a tag. When you check out that +version in your VCS -- for example, tag `v1.1` or commit `e35fa0d` --, you're +asking for a single, known set of files, and you always get the same files back. + +In Composer, what's usually referred to casually as a version -- that is, +the string that follows the package name in a require line (e.g., `~1.1` or +`1.2.*`) -- is actually more specifically a version constraint. Composer +uses version constraints to figure out which refs in a VCS it should be +checking out. + +### Tags vs Branches + +Normally, Composer deals with tags (as opposed to branches -- if you don't +know what this means, read up on +[version control systems](https://en.wikipedia.org/wiki/Version_control#Common_vocabulary)). +When referencing a tag, it may reference a specific tag (e.g., `1.1`) or it +may reference a valid range of tags (e.g., `>=1.1 <2.0`). Furthermore, you +can add "stability specifiers" to let Composer know that you are or aren't +interested in certain tags, like alpha releases, beta releases, or release +candidates, even if they're technically within the numeric range specified +by the version constraint (these releases are usually considered "unstable", +hence the term "stability specifier"). + +If you want Composer to check out a branch instead of a tag, you use the +special syntax described [here](02-libraries.md#branches). In short, if +you're checking out a branch, it's assumed that you want to *work* on the +branch and Composer simply clones the repo into the correct place in your +`vendor` directory. (For tags, it just copies the right files without actually +cloning the repo.) This can be very convenient for libraries under development, +as you can make changes to the dependency files your project is actually using +and still commit them to their respective repos as patches or other updates. + +Let's look at an example. Suppose you've published a library whose git repo +looks like this: + +```sh +$ git branch +$ +$ v1 +$ v2 +$ my-feature +$ nother-feature +$ +$ git tag +$ +$ v1.0 +$ v1.0.1 +$ v1.0.2 +$ v1.1-BETA +$ v1.1-RC1 +$ v1.1-RC2 +$ v1.1 +$ v1.1.1 +$ v2.0-BETA +$ v2.0-RC1 +$ v2.0 +$ v2.0.1 +$ v2.0.2 +``` + +Now assume you've got a project that depends on this library and you've been +running `composer update` in that project since the `v1.0` release. If you +specified `~1.0` in Composer (the tilde modifier, among others, is detailed +below), and you don't add a [`minimum-stability`](04-schema.md#minimum-stability) +key elsewhere in the file, then Composer will default to "stable" as a minimum +stability setting and you will receive only the `v1.0`, `v1.0.1`, `v1.0.2`, +`v1.1` and `v1.1.1` tags as the tags are created in your VCS. If you set the +`minimum-stability` key to `RC`, you would receive the aforementioned tags as +they're released, plus the `v1.1-RC1` and `v1.1-RC2` tags, but not `v1.1-BETA`. +(You can see the available stability constraints in order on the +[schema page](04-schema.md#minimum-stability). + +The final important detail here is how branches are handled. In git, a branch +simply represents a series of commits, with the current "HEAD" of the branch +pointing at the most recent in the chain. A tag is a specific commit, independent +of branch. By default composer checks out the tag that best matches the version +constraint you've specified. However, if you specify the version constraint as +"v1-dev" (or sometimes "dev-my-branch" -- see the [libraries page](02-libraries.md#branches) +for syntax details), then Composer will clone the repo into your `vendor` + directory, checking out the `v1` branch. + +## Basic Version Constraints + +Now that you have an idea of how Composer sees versions, let's talk about how +to specify version constraints for your project dependencies. ### Exact @@ -87,7 +177,7 @@ library code. Example: `^1.2.3` -## Stability +## Stability Constraints If you are using a constraint that does not explicitly define a stability, Composer will default internally to `-dev` or `-stable`, depending on the @@ -113,8 +203,9 @@ Examples: To allow various stabilities without enforcing them at the constraint level however, you may use [stability-flags](../04-schema.md#package-links) like `@` (e.g. `@dev`) to let composer know that a given package -can be installed in a different stability than your default -[minimum-stability](../04-schema.md#minimum-stability) setting. +can be installed in a different stability than your default minimum-stability +setting. All available stability flags are listed on the minimum-stability +section of the [schema page](../04-schema.md#minimum-stability). ## Test version constraints From c8c7619a4a9dbe25d202189728fe081c840d394b Mon Sep 17 00:00:00 2001 From: Kael Shipman Date: Mon, 23 Jan 2017 13:06:51 -0600 Subject: [PATCH 03/15] Finished reworking docs to clarify points about versioning (fixes #6088) --- doc/01-basic-usage.md | 41 +++++++++++-- doc/02-libraries.md | 101 ++++++-------------------------- doc/04-schema.md | 9 +-- doc/articles/versions.md | 123 +++++++++++++++++++-------------------- 4 files changed, 118 insertions(+), 156 deletions(-) diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index 3aea1a1ed..308fae5c6 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -48,7 +48,10 @@ will be identical - the vendor name just exists to prevent naming clashes. For example, it would allow two different people to create a library named `json`. One might be named `igorw/json` while the other might be `seldaek/json`. -Read more about publishing packages and package naming [here](02-libraries.md) +Read more about publishing packages and package naming [here](02-libraries.md). +(Note that you can also specify "platform packages" as dependencies, allowing +you to require certain versions of server software. See +[platform packages](#platform-packages) below.) ### Package Version Constraints @@ -57,8 +60,8 @@ In our example, we're requesting the Monolog package with the version constraint This means any version in the `1.0` development branch, or any version that is greater than or equal to 1.0 and less than 1.1 (`>=1.0 <1.1`). -Version can be a little confusing in Composer, and version constraints can be specified -in several ways. Please read [versions](articles/versions.md) for more in-depth information. +(What the term "version" actually means can be a little confusing in Composer. +Please read [versions](articles/versions.md) for more in-depth information.) > **How does Composer download the right files?** When you specify a dependency in > `composer.json`, Composer, first takes the name of the package that you've requested @@ -69,7 +72,7 @@ in several ways. Please read [versions](articles/versions.md) for more in-depth > > When it finds the right package, either in Packagist or in a repo you've specified, > it then uses the versioning features of the package's VCS (i.e., branches and tags) -> to attempt to find the best match for the version you've specified. Be sure to read +> to attempt to find the best match for the version constraint you've specified. Be sure to read > about versions and package resolution in the [versions article](articles/versions.md). > **Note:** If you're trying to require a package but Composer throws an error @@ -108,7 +111,8 @@ folders under `vendor/`. When Composer has finished installing, it writes all of the packages and the exact versions of them that it downloaded to the `composer.lock` file, locking the project to those specific -versions. +versions. You should commit the `composer.lock` file to your project repo so that all people +working on the project are locked to the same versions of dependencies (more below). ### Installing With `composer.lock` @@ -122,7 +126,7 @@ all dependencies that you've listed in `composer.json`, but it uses the version that it finds in `composer.lock` to ensure that the package versions are consistent for everyone working on your project. The result is that you have all dependencies requested by your `composer.json` file, but that they may not all be at the very latest available versions (since -some of the dependencies listed in the `composer.lock` file may have released new versions since +some of the dependencies listed in the `composer.lock` file may have released newer versions since the file was created). This is by design, as it ensures that your project never breaks because of unexpected changes in dependencies. @@ -176,6 +180,31 @@ 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. +## Platform packages + +Composer has platform packages, which are virtual packages for things that are +installed on the system but are not actually installable by Composer. This +includes PHP itself, PHP extensions and some system libraries. + +* `php` represents the PHP version of the user, allowing you to apply + constraints, e.g. `>=5.4.0`. To require a 64bit version of php, you can + require the `php-64bit` package. + +* `hhvm` represents the version of the HHVM runtime (aka HipHop Virtual + Machine) and allows you to apply a constraint, e.g., '>=2.3.3'. + +* `ext-` allows you to require PHP extensions (includes core + extensions). Versioning can be quite inconsistent here, so it's often + a good idea to just set the constraint to `*`. An example of an extension + package name is `ext-gd`. + +* `lib-` allows constraints to be made on versions of libraries used by + PHP. The following are available: `curl`, `iconv`, `icu`, `libxml`, + `openssl`, `pcre`, `uuid`, `xsl`. + +You can use [`show --platform`](03-cli.md#show) to get a list of your locally +available platform packages. + ## Autoloading For libraries that specify autoload information, Composer generates a diff --git a/doc/02-libraries.md b/doc/02-libraries.md index 51eb004b7..cfbc6b681 100644 --- a/doc/02-libraries.md +++ b/doc/02-libraries.md @@ -8,7 +8,7 @@ Composer. As soon as you have a `composer.json` in a directory, that directory is a 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. +your project and a library 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 the [`name`](04-schema.md#name) property in `composer.json`: @@ -29,40 +29,18 @@ name. Supplying a vendor name is mandatory. > username is usually a good bet. While package names are case insensitive, the > convention is all lowercase and dashes for word separation. -## Platform packages +## Library Versioning -Composer has platform packages, which are virtual packages for things that are -installed on the system but are not actually installable by Composer. This -includes PHP itself, PHP extensions and some system libraries. +In the vast majority of cases, you will be maintaining your library using some +sort of version control system like git, svn, hg or fossil. In these cases, +Composer infers versions from your VCS and you **should not** specify a version +in your `composer.json` file. (See the [Versions article](articles/versions.md) +to learn about how Composer uses VCS branches and tags to resolve version +constraints.) -* `php` represents the PHP version of the user, allowing you to apply - constraints, e.g. `>=5.4.0`. To require a 64bit version of php, you can - require the `php-64bit` package. - -* `hhvm` represents the version of the HHVM runtime (aka HipHop Virtual - Machine) and allows you to apply a constraint, e.g., '>=2.3.3'. - -* `ext-` allows you to require PHP extensions (includes core - extensions). Versioning can be quite inconsistent here, so it's often - a good idea to just set the constraint to `*`. An example of an extension - package name is `ext-gd`. - -* `lib-` allows constraints to be made on versions of libraries used by - PHP. The following are available: `curl`, `iconv`, `icu`, `libxml`, - `openssl`, `pcre`, `uuid`, `xsl`. - -You can use [`show --platform`](03-cli.md#show) to get a list of your locally -available platform packages. - -## Specifying the version - -When you publish your package on Packagist, it is able to infer the version -from the VCS (git, svn, hg, fossil) 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, -you can just add a `version` field: +If you are maintaining packages by hand (i.e., without a VCS), you'll need to +specify the version explicitly by adding a `version` value in your `composer.json` +file: ```json { @@ -70,57 +48,16 @@ you can just add a `version` field: } ``` -> **Note:** You should avoid specifying the version field explicitly, because -> for tags the value must match the tag name. +### VCS Versioning -### Tags +Composer uses your VCS's branch and tag features to resolve the version +constraints you specify in your `require` field to specific sets of files. +When determining valid available versions, Composer looks at all of your tags +and branches and translates their names into an internal list of options that +it then matches against the version constraint you've provided. -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 suffix can also -be followed by a number. - -Here are a few examples of valid tag names: - -- 1.0.0 -- v1.0.0 -- 1.10.5-RC1 -- v4.4.4-beta2 -- 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`). - -### 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. - -Here are some examples of version branch names: - -- 1.x -- 1.0 (equals 1.0.x) -- 1.1.x - -> **Note:** When you install a development version, it will be automatically -> pulled from its `source`. See the [`install`](03-cli.md#install) command -> for more details. - -### 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. - -See [Aliases](articles/aliases.md) for more information. +For more on how Composer treats tags and branches and how it resolves package +version constraints, read the [versions](articles/versions.md) article. ## Lock file diff --git a/doc/04-schema.md b/doc/04-schema.md index 0e96f131b..59d2c39da 100644 --- a/doc/04-schema.md +++ b/doc/04-schema.md @@ -255,7 +255,8 @@ Optional. ### Package links All of the following take an object which maps package names to -[version constraints](01-basic-usage.md#package-versions). +versions of the package via version constraints. Read more about +versions [here](articles/versions.md). Example: @@ -680,9 +681,9 @@ it in your file to avoid surprises. All versions of each package are checked for stability, and those that are less stable than the `minimum-stability` setting will be ignored when resolving -your project dependencies. Specific changes to the stability requirements of -a given package can be done in `require` or `require-dev` (see -[package links](#package-links)). +your project dependencies. (Note that you can also specify stability requirements +on a per-package basis using stability flags in the version constraints that you +specify in a `require` block (see [package links](#package-links) for more details). Available options (in order of stability) are `dev`, `alpha`, `beta`, `RC`, and `stable`. diff --git a/doc/articles/versions.md b/doc/articles/versions.md index 3322361c4..43f2c08b4 100644 --- a/doc/articles/versions.md +++ b/doc/articles/versions.md @@ -14,84 +14,79 @@ which may be represented by a branch HEAD or a tag. When you check out that version in your VCS -- for example, tag `v1.1` or commit `e35fa0d` --, you're asking for a single, known set of files, and you always get the same files back. -In Composer, what's usually referred to casually as a version -- that is, +In Composer, what's often referred to casually as a version -- that is, the string that follows the package name in a require line (e.g., `~1.1` or `1.2.*`) -- is actually more specifically a version constraint. Composer uses version constraints to figure out which refs in a VCS it should be -checking out. +checking out (or simply to verify that a given library is acceptable in +the case of a statically-maintained library with a `version` specification +in `composer.json`). -### Tags vs Branches +## VCS Tags and Branches + +*For the following discussion, let's assume the following sample library +repository:* + +```sh +~/my-library$ git branch +~/my-library$ +~/my-library$ v1 +~/my-library$ v2 +~/my-library$ my-feature +~/my-library$ nother-feature +~/my-library$ +~/my-library$ git tag +~/my-library$ +~/my-library$ v1.0 +~/my-library$ v1.0.1 +~/my-library$ v1.0.2 +~/my-library$ v1.1-BETA +~/my-library$ v1.1-RC1 +~/my-library$ v1.1-RC2 +~/my-library$ v1.1 +~/my-library$ v1.1.1 +~/my-library$ v2.0-BETA +~/my-library$ v2.0-RC1 +~/my-library$ v2.0 +~/my-library$ v2.0.1 +~/my-library$ v2.0.2 +``` + +### Tags Normally, Composer deals with tags (as opposed to branches -- if you don't know what this means, read up on [version control systems](https://en.wikipedia.org/wiki/Version_control#Common_vocabulary)). -When referencing a tag, it may reference a specific tag (e.g., `1.1`) or it -may reference a valid range of tags (e.g., `>=1.1 <2.0`). Furthermore, you -can add "stability specifiers" to let Composer know that you are or aren't -interested in certain tags, like alpha releases, beta releases, or release -candidates, even if they're technically within the numeric range specified -by the version constraint (these releases are usually considered "unstable", -hence the term "stability specifier"). +When you write a version constraint, it may reference a specific tag (e.g., +`1.1`) or it may reference a valid range of tags (e.g., `>=1.1 <2.0`, or +`~4.0`). To resolve these constraints, Composer first asks the VCS to list +all available tags, then creates an internal list of available versions based +on these tags. In the above example, composer's internal list includes versions +`1.0`, `1.0.1`, `1.0.2`, the beta release of `1.1`, the first and second +release candidates of `1.1`, the final release version `1.1`, etc.... (Note +that Composer automatically removes the 'v' prefix in the actual tagname to +get a valid final version number.) -If you want Composer to check out a branch instead of a tag, you use the -special syntax described [here](02-libraries.md#branches). In short, if -you're checking out a branch, it's assumed that you want to *work* on the -branch and Composer simply clones the repo into the correct place in your -`vendor` directory. (For tags, it just copies the right files without actually -cloning the repo.) This can be very convenient for libraries under development, -as you can make changes to the dependency files your project is actually using -and still commit them to their respective repos as patches or other updates. +When it has a complete list of available versions from your VCS, it then +finds the highest version that matches all version constraints in your project +(it's possible that other packages require more specific versions of the +library than you do, so the version it chooses may not always be the highest +available version) and it downloads a zip archive of that tag to unpack in the +correct location in your `vendor` directory. -Let's look at an example. Suppose you've published a library whose git repo -looks like this: +### Branches -```sh -$ git branch -$ -$ v1 -$ v2 -$ my-feature -$ nother-feature -$ -$ git tag -$ -$ v1.0 -$ v1.0.1 -$ v1.0.2 -$ v1.1-BETA -$ v1.1-RC1 -$ v1.1-RC2 -$ v1.1 -$ v1.1.1 -$ v2.0-BETA -$ v2.0-RC1 -$ v2.0 -$ v2.0.1 -$ v2.0.2 -``` +If you want Composer to check out a branch instead of a tag, there's a special syntax. If you're checking out a branch, it's assumed that you want to *work* on the branch and Composer actually clones the repo into the correct place in your `vendor` directory. (For tags, it just copies the right files without actually cloning the repo.) To get Composer to do this, you need to point it to the branch using the special `dev-*` prefix (or sometimes suffix; see below). -Now assume you've got a project that depends on this library and you've been -running `composer update` in that project since the `v1.0` release. If you -specified `~1.0` in Composer (the tilde modifier, among others, is detailed -below), and you don't add a [`minimum-stability`](04-schema.md#minimum-stability) -key elsewhere in the file, then Composer will default to "stable" as a minimum -stability setting and you will receive only the `v1.0`, `v1.0.1`, `v1.0.2`, -`v1.1` and `v1.1.1` tags as the tags are created in your VCS. If you set the -`minimum-stability` key to `RC`, you would receive the aforementioned tags as -they're released, plus the `v1.1-RC1` and `v1.1-RC2` tags, but not `v1.1-BETA`. -(You can see the available stability constraints in order on the -[schema page](04-schema.md#minimum-stability). +In the above example, if I wanted to check out the `my-feature` branch, I would specify `dev-my-feature` as the version constraint in my `require` clause. This would result in Composer cloning the `my-library` repository into my `vendor` directory and checking out the `my-feature` branch. -The final important detail here is how branches are handled. In git, a branch -simply represents a series of commits, with the current "HEAD" of the branch -pointing at the most recent in the chain. A tag is a specific commit, independent -of branch. By default composer checks out the tag that best matches the version -constraint you've specified. However, if you specify the version constraint as -"v1-dev" (or sometimes "dev-my-branch" -- see the [libraries page](02-libraries.md#branches) -for syntax details), then Composer will clone the repo into your `vendor` - directory, checking out the `v1` branch. +The exception to this is when branch names look like versions. In that case, we have to clarify for composer that we're trying to check out a branch and not a tag. In the above example, we have two version branches, `v1` and `v2`. To get Composer to check out one of these branches, you must specify a version constraint that looks like this: `v1.x-dev`. There are two things to notice here. First, the `.x`: this is an arbitrary string that Composer requires us to append to tell it that we're talking about the `v1` branch and not a `v1` tag (alternatively, you can just name the branch `v1.x` instead of `v1`). Second, notice that in the case of a branch with a version-like name (`v1`, in this case), you append `-dev` as a suffix, rather than `dev-` as a prefix. -## Basic Version Constraints +### Minimum Stability + +There's one more thing that will affect which files are checked out of a library's VCS and added to your project: Composer allows you to specify stability constraints to limit which tags are considered valid. In the above example, notice that the library released a beta and two release candidates for version `1.1` before the final official release. In order to receive those versions when we run `composer install` or `composer update`, we have to explicitly tell composer that we're ok with release candidates and beta releases (and alpha releases, if we want those). This can be done using either a project-wide `minimum-stability` value in `composer.json` or using "stability flags" in version constraints. Read more on the [schema page](04-schema.md#minimum-stability). + +## Writing Basic Version Constraints Now that you have an idea of how Composer sees versions, let's talk about how to specify version constraints for your project dependencies. From c15baed33abe8c385e99b4de5d0363e49202326f Mon Sep 17 00:00:00 2001 From: Nils Adermann Date: Wed, 8 Mar 2017 10:15:27 +0100 Subject: [PATCH 04/15] Docs: Clarify what "It" stands for --- doc/01-basic-usage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index 308fae5c6..4c17a9f2d 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -33,7 +33,7 @@ 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.*`). -It uses this information to search for the right set of files in package +Composer uses this information to search for the right set of files in package "repositories" that you register using the [`repositories`](04-schema.md#repositories) key, or in Packagist, the default package respository. In the above example, since no other repository has been registered in the `composer.json` file, it is From 7bdc929e6d6488d7c0690e4f6d4458297e2754b8 Mon Sep 17 00:00:00 2001 From: Nils Adermann Date: Wed, 8 Mar 2017 10:23:14 +0100 Subject: [PATCH 05/15] The confusing part is probably rather constraints and how versions work, not what they are --- doc/01-basic-usage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index 4c17a9f2d..44af62d90 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -60,8 +60,8 @@ In our example, we're requesting the Monolog package with the version constraint This means any version in the `1.0` development branch, or any version that is greater than or equal to 1.0 and less than 1.1 (`>=1.0 <1.1`). -(What the term "version" actually means can be a little confusing in Composer. -Please read [versions](articles/versions.md) for more in-depth information.) +Please read [versions](articles/versions.md) for more in-depth information on +versions, how versions relate to each other, and on version constraints. > **How does Composer download the right files?** When you specify a dependency in > `composer.json`, Composer, first takes the name of the package that you've requested From 18a4aecef58588ef6d0911e1afac7b5a6cc34b18 Mon Sep 17 00:00:00 2001 From: Nils Adermann Date: Wed, 8 Mar 2017 10:29:02 +0100 Subject: [PATCH 06/15] Docs: superfluous comma & it => Composer --- doc/01-basic-usage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index 44af62d90..1e66a84e4 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -64,13 +64,13 @@ Please read [versions](articles/versions.md) for more in-depth information on versions, how versions relate to each other, and on version constraints. > **How does Composer download the right files?** When you specify a dependency in -> `composer.json`, Composer, first takes the name of the package that you've requested +> `composer.json`, Composer first takes the name of the package that you've requested > and searches for it in any repositories that you've registered using the > [`repositories`](04-schema.md#repositories) key. If you haven't registered > any extra repositories, or it doesn't find a package with that name in the > repositories you've specified, it falls back to Packagist (more [below](#packagist)). > -> When it finds the right package, either in Packagist or in a repo you've specified, +> When Composer finds the right package, either in Packagist or in a repo you've specified, > it then uses the versioning features of the package's VCS (i.e., branches and tags) > to attempt to find the best match for the version constraint you've specified. Be sure to read > about versions and package resolution in the [versions article](articles/versions.md). From 586e0d6cdb95e257a2aae7c31b240300b0e4d802 Mon Sep 17 00:00:00 2001 From: Nils Adermann Date: Wed, 8 Mar 2017 10:36:27 +0100 Subject: [PATCH 07/15] Docs: composer.lock lists versions, not constraints --- doc/01-basic-usage.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index 1e66a84e4..9127530da 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -122,12 +122,12 @@ This brings us to the second scenario. If there's already a `composer.lock` file committed the `composer.lock` file to the project (which is good). Either way, running `install` when a `composer.lock` file is present simply resolves and installs -all dependencies that you've listed in `composer.json`, but it uses the version constraints -that it finds in `composer.lock` to ensure that the package versions are consistent for everyone +all dependencies that you've listed in `composer.json`, but it uses the exact versions listed +in `composer.lock` to ensure that the package versions are consistent for everyone working on your project. The result is that you have all dependencies requested by your `composer.json` file, but that they may not all be at the very latest available versions (since some of the dependencies listed in the `composer.lock` file may have released newer versions since -the file was created). This is by design, as it ensures that your project never breaks because of +the file was created). This is by design, it ensures that your project does not break because of unexpected changes in dependencies. ### Commit Your `composer.lock` File to Version Control From 4ccf5b6535417edf86b78489e8ab90902125b2c7 Mon Sep 17 00:00:00 2001 From: Nils Adermann Date: Wed, 8 Mar 2017 10:42:54 +0100 Subject: [PATCH 08/15] Docs: don't use short forms, it => composer --- doc/01-basic-usage.md | 46 +++++++++++++++++++++---------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index 9127530da..33a4e4a49 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -18,7 +18,7 @@ other metadata as well. ### The `require` Key The first (and often only) thing you specify in `composer.json` is the -[`require`](04-schema.md#require) key. You're simply telling Composer which +[`require`](04-schema.md#require) key. You are simply telling Composer which packages your project depends on. ```json @@ -55,7 +55,7 @@ you to require certain versions of server software. See ### Package Version Constraints -In our example, we're requesting the Monolog package with the version constraint +In our example, we are requesting the Monolog package with the version constraint [`1.0.*`](http://semver.mwl.be/#?package=monolog%2Fmonolog&version=1.0.*). This means any version in the `1.0` development branch, or any version that is greater than or equal to 1.0 and less than 1.1 (`>=1.0 <1.1`). @@ -64,23 +64,23 @@ Please read [versions](articles/versions.md) for more in-depth information on versions, how versions relate to each other, and on version constraints. > **How does Composer download the right files?** When you specify a dependency in -> `composer.json`, Composer first takes the name of the package that you've requested -> and searches for it in any repositories that you've registered using the -> [`repositories`](04-schema.md#repositories) key. If you haven't registered -> any extra repositories, or it doesn't find a package with that name in the -> repositories you've specified, it falls back to Packagist (more [below](#packagist)). +> `composer.json`, Composer first takes the name of the package that you have requested +> and searches for it in any repositories that you have registered using the +> [`repositories`](04-schema.md#repositories) key. If you have not registered +> any extra repositories, or it does not find a package with that name in the +> repositories you have specified, it falls back to Packagist (more [below](#packagist)). > -> When Composer finds the right package, either in Packagist or in a repo you've specified, +> When Composer finds the right package, either in Packagist or in a repo you have specified, > it then uses the versioning features of the package's VCS (i.e., branches and tags) -> to attempt to find the best match for the version constraint you've specified. Be sure to read +> to attempt to find the best match for the version constraint you have specified. Be sure to read > about versions and package resolution in the [versions article](articles/versions.md). -> **Note:** If you're trying to require a package but Composer throws an error -> regarding package stability, the version you've specified may not meet your +> **Note:** If you are trying to require a package but Composer throws an error +> regarding package stability, the version you have specified may not meet your > default minimum stability requirements. By default only stable releases are taken > into consideration when searching for valid package versions in your VCS. > -> You might run into this if you're trying to require dev, alpha, beta, or RC +> You might run into this if you are trying to require dev, alpha, beta, or RC > versions of a package. Read more about stability flags and the `minimum-stability` > key on the [schema page](04-schema.md). @@ -97,7 +97,7 @@ When you run this command, one of two things may happen: ### Installing Without `composer.lock` -If you've never run the command before and there is also no `composer.lock` file present, +If you have never run the command before and there is also no `composer.lock` file present, Composer simply resolves all dependencies listed in your `composer.json` file and downloads the latest version of their files into the `vendor` directory in your project. (The `vendor` directory is the conventional location for all third-party code in a project). In our @@ -116,17 +116,17 @@ working on the project are locked to the same versions of dependencies (more bel ### Installing With `composer.lock` -This brings us to the second scenario. If there's already a `composer.lock` file as well as a -`composer.json` file when you run `composer install`, it means that either you've run the -`install` command before, or someone else on the project has run the `install` command and +This brings us to the second scenario. If there is already a `composer.lock` file as well as a +`composer.json` file when you run `composer install`, it means either you ran the +`install` command before, or someone else on the project ran the `install` command and committed the `composer.lock` file to the project (which is good). -Either way, running `install` when a `composer.lock` file is present simply resolves and installs -all dependencies that you've listed in `composer.json`, but it uses the exact versions listed +Either way, running `install` when a `composer.lock` file is present resolves and installs +all dependencies that you listed in `composer.json`, but Composer uses the exact versions listed in `composer.lock` to ensure that the package versions are consistent for everyone -working on your project. The result is that you have all dependencies requested by your -`composer.json` file, but that they may not all be at the very latest available versions (since -some of the dependencies listed in the `composer.lock` file may have released newer versions since +working on your project. As a result you will have all dependencies requested by your +`composer.json` file, but they may not all be at the very latest available versions +(some of the dependencies listed in the `composer.lock` file may have released newer versions since the file was created). This is by design, it ensures that your project does not break because of unexpected changes in dependencies. @@ -134,7 +134,7 @@ unexpected changes in dependencies. Committing this file to VC is important because it will cause anyone who sets up the project to use the exact same -versions of the dependencies that you're using. Your CI server, production +versions of the dependencies that you are using. Your CI server, production machines, other developers in your team, everything and everyone runs on the same dependencies, which mitigates the potential for bugs affecting only some parts of the deployments. Even if you develop alone, in six months when @@ -177,7 +177,7 @@ 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 is recommended to publish their packages -on Packagist. A library doesn't need to be on Packagist to be used by Composer, +on Packagist. A library does not need to be on Packagist to be used by Composer, but it enables discovery and adoption by other developers more quickly. ## Platform packages From 78565d00b94973010efff1cbd600becdef394824 Mon Sep 17 00:00:00 2001 From: Nils Adermann Date: Wed, 8 Mar 2017 10:45:46 +0100 Subject: [PATCH 09/15] Docs: versions plural, and update == rm lock&install --- doc/01-basic-usage.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index 33a4e4a49..9ddcfcf5f 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -147,8 +147,9 @@ still working even if your dependencies released many new versions since then. As mentioned above, the `composer.lock` file prevents you from automatically getting the latest versions of your dependencies. To update to the latest versions, use the [`update`](03-cli.md#update) 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 is equivalent to simply deleting the `composer.lock` file.) +versions (according to your `composer.json` file) and update the lock file +with the new versions. (This is equivalent to deleting the `composer.lock` file +and running `install` again.) ```sh php composer.phar update From faac4d56b48a82546b1fdab8aeb8d171bb7a9615 Mon Sep 17 00:00:00 2001 From: Nils Adermann Date: Wed, 8 Mar 2017 10:49:06 +0100 Subject: [PATCH 10/15] Docs: HHVM is not called HipHop --- doc/01-basic-usage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index 9ddcfcf5f..b4c5db96a 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -191,8 +191,8 @@ includes PHP itself, PHP extensions and some system libraries. constraints, e.g. `>=5.4.0`. To require a 64bit version of php, you can require the `php-64bit` package. -* `hhvm` represents the version of the HHVM runtime (aka HipHop Virtual - Machine) and allows you to apply a constraint, e.g., '>=2.3.3'. +* `hhvm` represents the version of the HHVM runtime and allows you to apply + a constraint, e.g., '>=2.3.3'. * `ext-` allows you to require PHP extensions (includes core extensions). Versioning can be quite inconsistent here, so it's often From d835983b15f030ef9e699f8ece470840fac92f52 Mon Sep 17 00:00:00 2001 From: Nils Adermann Date: Wed, 8 Mar 2017 10:58:55 +0100 Subject: [PATCH 11/15] Docs: Add back a second clear note about hardcoded versions in VCS --- doc/02-libraries.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/02-libraries.md b/doc/02-libraries.md index cfbc6b681..e59f505dd 100644 --- a/doc/02-libraries.md +++ b/doc/02-libraries.md @@ -48,13 +48,16 @@ file: } ``` +> **Note:** When you add a hardcoded version to a VCS, the version will conflict +> with tag names. Composer will not be able to determine the version number. + ### VCS Versioning Composer uses your VCS's branch and tag features to resolve the version constraints you specify in your `require` field to specific sets of files. When determining valid available versions, Composer looks at all of your tags and branches and translates their names into an internal list of options that -it then matches against the version constraint you've provided. +it then matches against the version constraint you provided. For more on how Composer treats tags and branches and how it resolves package version constraints, read the [versions](articles/versions.md) article. From 138fb5b6af54c915c99a8bca55982dcc323e09c0 Mon Sep 17 00:00:00 2001 From: Nils Adermann Date: Wed, 8 Mar 2017 11:02:24 +0100 Subject: [PATCH 12/15] Docs: Fix shell sample output --- doc/articles/versions.md | 38 ++++++++++++++++++-------------------- 1 file changed, 18 insertions(+), 20 deletions(-) diff --git a/doc/articles/versions.md b/doc/articles/versions.md index 43f2c08b4..b922e49d2 100644 --- a/doc/articles/versions.md +++ b/doc/articles/versions.md @@ -29,27 +29,25 @@ repository:* ```sh ~/my-library$ git branch -~/my-library$ -~/my-library$ v1 -~/my-library$ v2 -~/my-library$ my-feature -~/my-library$ nother-feature -~/my-library$ +v1 +v2 +my-feature +nother-feature + ~/my-library$ git tag -~/my-library$ -~/my-library$ v1.0 -~/my-library$ v1.0.1 -~/my-library$ v1.0.2 -~/my-library$ v1.1-BETA -~/my-library$ v1.1-RC1 -~/my-library$ v1.1-RC2 -~/my-library$ v1.1 -~/my-library$ v1.1.1 -~/my-library$ v2.0-BETA -~/my-library$ v2.0-RC1 -~/my-library$ v2.0 -~/my-library$ v2.0.1 -~/my-library$ v2.0.2 +v1.0 +v1.0.1 +v1.0.2 +v1.1-BETA +v1.1-RC1 +v1.1-RC2 +v1.1 +v1.1.1 +v2.0-BETA +v2.0-RC1 +v2.0 +v2.0.1 +v2.0.2 ``` ### Tags From 4a20d5d98b8395eb84e71fc5a2166fad8e46ca65 Mon Sep 17 00:00:00 2001 From: Nils Adermann Date: Wed, 8 Mar 2017 11:10:51 +0100 Subject: [PATCH 13/15] Docs: notice => note --- doc/articles/versions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/articles/versions.md b/doc/articles/versions.md index b922e49d2..c0c5f9876 100644 --- a/doc/articles/versions.md +++ b/doc/articles/versions.md @@ -65,7 +65,7 @@ release candidates of `1.1`, the final release version `1.1`, etc.... (Note that Composer automatically removes the 'v' prefix in the actual tagname to get a valid final version number.) -When it has a complete list of available versions from your VCS, it then +When Composer has a complete list of available versions from your VCS, it then finds the highest version that matches all version constraints in your project (it's possible that other packages require more specific versions of the library than you do, so the version it chooses may not always be the highest @@ -78,11 +78,11 @@ If you want Composer to check out a branch instead of a tag, there's a special s In the above example, if I wanted to check out the `my-feature` branch, I would specify `dev-my-feature` as the version constraint in my `require` clause. This would result in Composer cloning the `my-library` repository into my `vendor` directory and checking out the `my-feature` branch. -The exception to this is when branch names look like versions. In that case, we have to clarify for composer that we're trying to check out a branch and not a tag. In the above example, we have two version branches, `v1` and `v2`. To get Composer to check out one of these branches, you must specify a version constraint that looks like this: `v1.x-dev`. There are two things to notice here. First, the `.x`: this is an arbitrary string that Composer requires us to append to tell it that we're talking about the `v1` branch and not a `v1` tag (alternatively, you can just name the branch `v1.x` instead of `v1`). Second, notice that in the case of a branch with a version-like name (`v1`, in this case), you append `-dev` as a suffix, rather than `dev-` as a prefix. +The exception to this is when branch names look like versions. In that case, we have to clarify for composer that we're trying to check out a branch and not a tag. In the above example, we have two version branches, `v1` and `v2`. To get Composer to check out one of these branches, you must specify a version constraint that looks like this: `v1.x-dev`. There are two things to note here. First, the `.x`: this is an arbitrary string that Composer requires us to append to tell it that we're talking about the `v1` branch and not a `v1` tag (alternatively, you can just name the branch `v1.x` instead of `v1`). Second, in the case of a branch with a version-like name (`v1`, in this case), you append `-dev` as a suffix, rather than `dev-` as a prefix. ### Minimum Stability -There's one more thing that will affect which files are checked out of a library's VCS and added to your project: Composer allows you to specify stability constraints to limit which tags are considered valid. In the above example, notice that the library released a beta and two release candidates for version `1.1` before the final official release. In order to receive those versions when we run `composer install` or `composer update`, we have to explicitly tell composer that we're ok with release candidates and beta releases (and alpha releases, if we want those). This can be done using either a project-wide `minimum-stability` value in `composer.json` or using "stability flags" in version constraints. Read more on the [schema page](04-schema.md#minimum-stability). +There's one more thing that will affect which files are checked out of a library's VCS and added to your project: Composer allows you to specify stability constraints to limit which tags are considered valid. In the above example, note that the library released a beta and two release candidates for version `1.1` before the final official release. In order to receive those versions when we run `composer install` or `composer update`, we have to explicitly tell composer that we're ok with release candidates and beta releases (and alpha releases, if we want those). This can be done using either a project-wide `minimum-stability` value in `composer.json` or using "stability flags" in version constraints. Read more on the [schema page](04-schema.md#minimum-stability). ## Writing Basic Version Constraints From 6c07bb1fb7ad149adfc9a569db425d81bccf0b39 Mon Sep 17 00:00:00 2001 From: Nils Adermann Date: Wed, 8 Mar 2017 11:13:08 +0100 Subject: [PATCH 14/15] Docs: those/these composer/Composer --- doc/articles/versions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/articles/versions.md b/doc/articles/versions.md index c0c5f9876..3e843a16a 100644 --- a/doc/articles/versions.md +++ b/doc/articles/versions.md @@ -82,7 +82,7 @@ The exception to this is when branch names look like versions. In that case, we ### Minimum Stability -There's one more thing that will affect which files are checked out of a library's VCS and added to your project: Composer allows you to specify stability constraints to limit which tags are considered valid. In the above example, note that the library released a beta and two release candidates for version `1.1` before the final official release. In order to receive those versions when we run `composer install` or `composer update`, we have to explicitly tell composer that we're ok with release candidates and beta releases (and alpha releases, if we want those). This can be done using either a project-wide `minimum-stability` value in `composer.json` or using "stability flags" in version constraints. Read more on the [schema page](04-schema.md#minimum-stability). +There's one more thing that will affect which files are checked out of a library's VCS and added to your project: Composer allows you to specify stability constraints to limit which tags are considered valid. In the above example, note that the library released a beta and two release candidates for version `1.1` before the final official release. To receive these versions when running `composer install` or `composer update`, we have to explicitly tell Composer that we are ok with release candidates and beta releases (and alpha releases, if we want those). This can be done using either a project-wide `minimum-stability` value in `composer.json` or using "stability flags" in version constraints. Read more on the [schema page](04-schema.md#minimum-stability). ## Writing Basic Version Constraints From cd224ad44b9085d8cd5e929ec9d628b41f419a5a Mon Sep 17 00:00:00 2001 From: Nils Adermann Date: Wed, 8 Mar 2017 11:20:23 +0100 Subject: [PATCH 15/15] Docs: cleanup version branches section --- doc/articles/versions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/articles/versions.md b/doc/articles/versions.md index 3e843a16a..250b8c987 100644 --- a/doc/articles/versions.md +++ b/doc/articles/versions.md @@ -74,11 +74,11 @@ correct location in your `vendor` directory. ### Branches -If you want Composer to check out a branch instead of a tag, there's a special syntax. If you're checking out a branch, it's assumed that you want to *work* on the branch and Composer actually clones the repo into the correct place in your `vendor` directory. (For tags, it just copies the right files without actually cloning the repo.) To get Composer to do this, you need to point it to the branch using the special `dev-*` prefix (or sometimes suffix; see below). +If you want Composer to check out a branch instead of a tag, you need to point it to the branch using the special `dev-*` prefix (or sometimes suffix; see below). If you're checking out a branch, it's assumed that you want to *work* on the branch and Composer actually clones the repo into the correct place in your `vendor` directory. For tags, it just copies the right files without actually cloning the repo. (You can modify this behavior with --prefer-source and --prefer-dist, see [install options](03-cli.md#install).) -In the above example, if I wanted to check out the `my-feature` branch, I would specify `dev-my-feature` as the version constraint in my `require` clause. This would result in Composer cloning the `my-library` repository into my `vendor` directory and checking out the `my-feature` branch. +In the above example, if you wanted to check out the `my-feature` branch, you would specify `dev-my-feature` as the version constraint in your `require` clause. This would result in Composer cloning the `my-library` repository into my `vendor` directory and checking out the `my-feature` branch. -The exception to this is when branch names look like versions. In that case, we have to clarify for composer that we're trying to check out a branch and not a tag. In the above example, we have two version branches, `v1` and `v2`. To get Composer to check out one of these branches, you must specify a version constraint that looks like this: `v1.x-dev`. There are two things to note here. First, the `.x`: this is an arbitrary string that Composer requires us to append to tell it that we're talking about the `v1` branch and not a `v1` tag (alternatively, you can just name the branch `v1.x` instead of `v1`). Second, in the case of a branch with a version-like name (`v1`, in this case), you append `-dev` as a suffix, rather than `dev-` as a prefix. +When branch names look like versions, we have to clarify for composer that we're trying to check out a branch and not a tag. In the above example, we have two version branches: `v1` and `v2`. To get Composer to check out one of these branches, you must specify a version constraint that looks like this: `v1.x-dev`. The `.x` is an arbitrary string that Composer requires to tell it that we're talking about the `v1` branch and not a `v1` tag (alternatively, you can just name the branch `v1.x` instead of `v1`). In the case of a branch with a version-like name (`v1`, in this case), you append `-dev` as a suffix, rather than using `dev-` as a prefix. ### Minimum Stability