From c8c7619a4a9dbe25d202189728fe081c840d394b Mon Sep 17 00:00:00 2001 From: Kael Shipman Date: Mon, 23 Jan 2017 13:06:51 -0600 Subject: [PATCH] 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.