From 7377db32aeddf4106a72dfe71671770ad5596ed9 Mon Sep 17 00:00:00 2001 From: Rob Bast Date: Mon, 3 Oct 2016 10:14:57 +0200 Subject: [PATCH] remove 'includes' references from docs Relates to #5739 - we do not want to mention attributes/properties that are considered legacy and/or deprecated. Also reflowed some lines. --- doc/05-repositories.md | 112 +++++-------- doc/fixtures/fixtures.md | 19 ++- ...86b937f0502d92f776072cd49c002dca742b9.json | 158 ------------------ .../repo-composer-with-includes/packages.json | 10 -- 4 files changed, 55 insertions(+), 244 deletions(-) delete mode 100644 doc/fixtures/repo-composer-with-includes/include/all$5fa86b937f0502d92f776072cd49c002dca742b9.json delete mode 100644 doc/fixtures/repo-composer-with-includes/packages.json diff --git a/doc/05-repositories.md b/doc/05-repositories.md index f29d4187f..bd1d24cbb 100644 --- a/doc/05-repositories.md +++ b/doc/05-repositories.md @@ -20,10 +20,10 @@ In fact, internally Composer sees every version as a separate package. While this distinction does not matter when you are using Composer, it's quite important when you want to change it. -In addition to the name and the version, there is useful metadata. The information -most relevant for installation is the source definition, which describes where -to get the package contents. The package data points to the contents of the -package. And there are two options here: dist and source. +In addition to the name and the version, there is useful metadata. The +information most relevant for installation is the source definition, which +describes where to get the package contents. The package data points to the +contents of the package. And there are two options here: dist and source. **Dist:** The dist is a packaged version of the package data. Usually a released version, usually a stable release. @@ -132,45 +132,15 @@ number. This field is optional. -#### includes - -For larger repositories it is possible to split the `packages.json` into -multiple files. The `includes` field allows you to reference these additional -files. - -An example: - -```json -{ - "includes": { - "packages-2011.json": { - "sha1": "525a85fb37edd1ad71040d429928c2c0edec9d17" - }, - "packages-2012-01.json": { - "sha1": "897cde726f8a3918faf27c803b336da223d400dd" - }, - "packages-2012-02.json": { - "sha1": "26f911ad717da26bbcac3f8f435280d13917efa5" - } - } -} -``` - -The SHA-1 sum of the file allows it to be cached and only re-requested if the -hash changed. - -This field is optional. You probably don't need it for your own custom -repository. - #### provider-includes and providers-url -For very large repositories like packagist.org using the so-called provider -files is the preferred method. The `provider-includes` field allows you to -list a set of files that list package names provided by this repository. The -hash should be a sha256 of the files in this case. +The `provider-includes` field allows you to list a set of files that list +package names provided by this repository. The hash should be a sha256 of +the files in this case. The `providers-url` describes how provider files are found on the server. It -is an absolute path from the repository root. +is an absolute path from the repository root. It must contain the placeholders +`%package%` and `%hash%`. An example: @@ -206,24 +176,25 @@ integrity, for example: The file above declares that acme/foo and acme/bar can be found in this repository, by loading the file referenced by `providers-url`, replacing -`%package%` by the package name and `%hash%` by the sha256 field. Those files -themselves just contain package definitions as described [above](#packages). +`%package%` by the vendor namespaced package name and `%hash%` by the +sha256 field. Those files themselves just contain package definitions as +described [above](#packages). -This field is optional. You probably don't need it for your own custom +These fields are optional. You probably don't need them for your own custom repository. #### stream options -The `packages.json` file is loaded using a PHP stream. You can set extra options -on that stream using the `options` parameter. You can set any valid PHP stream -context option. See [Context options and parameters](https://php.net/manual/en/context.php) -for more information. +The `packages.json` file is loaded using a PHP stream. You can set extra +options on that stream using the `options` parameter. You can set any valid +PHP stream context option. See [Context options and +parameters](https://php.net/manual/en/context.php) for more information. ### VCS VCS stands for version control system. This includes versioning systems like -git, svn, fossil or hg. Composer has a repository type for installing packages from -these systems. +git, svn, fossil or hg. Composer has a repository type for installing packages +from these systems. #### Loading a package from a VCS repository @@ -234,7 +205,8 @@ project to use the patched version. If the library is on GitHub (this is the case most of the time), you can simply fork it there and push your changes to your fork. After that you update the project's `composer.json`. All you have to do is add your fork as a repository and update the version constraint to -point to your custom branch. Your custom branch name must be prefixed with `"dev-"`. For version constraint naming conventions see +point to your custom branch. Your custom branch name must be prefixed with +`"dev-"`. For version constraint naming conventions see [Libraries](02-libraries.md) for more information. Example assuming you patched monolog to fix a bug in the `bugfix` branch: @@ -312,8 +284,8 @@ VCS repository provides `dist`s for them that fetch the packages as zips. * **BitBucket:** [bitbucket.org](https://bitbucket.org) (Git and Mercurial) The VCS driver to be used is detected automatically based on the URL. However, -should you need to specify one for whatever reason, you can use `fossil`, `git`, -`svn` or `hg` as the repository type instead of `vcs`. +should you need to specify one for whatever reason, you can use `fossil`, +`git`, `svn` or `hg` as the repository type instead of `vcs`. If you set the `no-api` key to `true` on a github repository it will clone the repository as it would with any other git repository instead of using the @@ -384,8 +356,9 @@ for this server will be overwritten. To change this behavior by setting the ### PEAR It is possible to install packages from any PEAR channel by using the `pear` -repository. Composer will prefix all package names with `pear-{channelName}/` to -avoid conflicts. All packages are also aliased with prefix `pear-{channelAlias}/` +repository. Composer will prefix all package names with `pear-{channelName}/` +to avoid conflicts. All packages are also aliased with prefix +`pear-{channelAlias}/`. Example using `pear2.php.net`: @@ -422,7 +395,8 @@ following packages: * `BasePackage` * `IntermediatePackage`, which depends on `BasePackage` - * `TopLevelPackage1` and `TopLevelPackage2` which both depend on `IntermediatePackage` + * `TopLevelPackage1` and `TopLevelPackage2` which both depend + on `IntermediatePackage` Without a vendor alias, Composer will use the PEAR channel name as the vendor portion of the package name: @@ -519,8 +493,8 @@ Typically you would leave the source part off, as you don't really need it. ## Hosting your own -While you will probably want to put your packages on packagist most of the time, -there are some use cases for hosting your own repository. +While you will probably want to put your packages on packagist most of the +time, there are some use cases for hosting your own repository. * **Private company packages:** If you are part of a company that uses Composer for their packages internally, you might want to keep those packages private. @@ -537,23 +511,24 @@ There are a few tools that can help you create a `composer` repository. ### Packagist -The underlying application used by packagist is open source. This means that you -can technically install your own copy of packagist. However it is not a +The underlying application used by packagist is open source. This means that +you can technically install your own copy of packagist. However it is not a supported use case and changes will happen without caring for third parties using the code. Packagist is a Symfony2 application, and it is [available on GitHub](https://github.com/composer/packagist). It uses Composer internally and -acts as a proxy between VCS repositories and the Composer users. It holds a list -of all VCS packages, periodically re-crawls them, and exposes them as a Composer -repository. +acts as a proxy between VCS repositories and the Composer users. It holds a +list of all VCS packages, periodically re-crawls them, and exposes them as a +Composer repository. ### Toran Proxy [Toran Proxy](https://toranproxy.com/) is a web app much like Packagist but providing private package hosting as well as mirroring/proxying of GitHub and -packagist.org. Check its homepage and the [Satis/Toran Proxy article](articles/handling-private-packages-with-satis.md) -for more information. +packagist.org. Check its homepage and the [Satis/Toran Proxy +article](articles/handling-private-packages-with-satis.md) for more +information. ### Satis @@ -623,8 +598,8 @@ For instance, if you have the following directory structure in your repository: \_ composer.json ``` -Then, to add the package `my/package` as a dependency, in your `apps/my-app/composer.json` -file, you can use the following configuration: +Then, to add the package `my/package` as a dependency, in your +`apps/my-app/composer.json` file, you can use the following configuration: ```json { @@ -650,9 +625,10 @@ the console will read `Symlinked from ../../packages/my-package`. If symlinking is _not_ possible the package will be copied. In that case, the console will output `Mirrored from ../../packages/my-package`. -Instead of default fallback strategy you can force to use symlink with `"symlink": true` -or mirroring with `"symlink": false` option. -Forcing mirroring can be useful when deploying or generating package from a monolithic repository. +Instead of default fallback strategy you can force to use symlink with +`"symlink": true` or mirroring with `"symlink": false` option. Forcing +mirroring can be useful when deploying or generating package from a +monolithic repository. ```json { diff --git a/doc/fixtures/fixtures.md b/doc/fixtures/fixtures.md index fd77f3c37..e689bfbd5 100644 --- a/doc/fixtures/fixtures.md +++ b/doc/fixtures/fixtures.md @@ -1,20 +1,23 @@ -`Composer` type repository fixtures -======================= +# `Composer` type repository fixtures -This directory contains some examples of what `composer` type repositories can look like. They serve as illustrating examples accompanying the docs, but can also be used as (initial) fixtures for tests. +This directory contains some examples of what `composer` type repositories can +look like. They serve as illustrating examples accompanying the docs, but can +also be used as (initial) fixtures for tests. * `repo-composer-plain` is a simple, plain `packages.json` file * `repo-composer-with-includes` uses the `includes` mechanism * `repo-composer-with-providers` uses the `providers` mechanism -Sample Packages used in these fixtures -------- +## Sample Packages used in these fixtures All these repositories contain the following packages. -* `foo/bar` versions 1.0.0, 1.0.1 and 1.1.0; dev-default and 1.0.x-dev branches. On dev-default and in 1.1.0, `bar/baz` ~1.0 is required. +* `foo/bar` versions 1.0.0, 1.0.1 and 1.1.0; dev-default and 1.0.x-dev branches. + On dev-default and in 1.1.0, `bar/baz` ~1.0 is required. * `qux/quux` only has a dev-default branch. It `replace`s `gar/nix`. -* `gar/nix` has a 1.0.0 version and a dev-default branch. It is being replaced by `qux/quux`. -* `bar/baz` has a 1.0.0 version and 1.0.x-dev as well as dev-default branches. Additionally, 1.1.x-dev is a branch alias for dev-default. +* `gar/nix` has a 1.0.0 version and a dev-default branch. It is being replaced + by `qux/quux`. +* `bar/baz` has a 1.0.0 version and 1.0.x-dev as well as dev-default branches. + Additionally, 1.1.x-dev is a branch alias for dev-default. diff --git a/doc/fixtures/repo-composer-with-includes/include/all$5fa86b937f0502d92f776072cd49c002dca742b9.json b/doc/fixtures/repo-composer-with-includes/include/all$5fa86b937f0502d92f776072cd49c002dca742b9.json deleted file mode 100644 index 219051998..000000000 --- a/doc/fixtures/repo-composer-with-includes/include/all$5fa86b937f0502d92f776072cd49c002dca742b9.json +++ /dev/null @@ -1,158 +0,0 @@ -{ - "packages": { - "bar/baz": { - "1.0.0": { - "name": "bar/baz", - "version": "1.0.0", - "version_normalized": "1.0.0.0", - "source": { - "type": "hg", - "url": "http://some.where/over/the/rainbow/", - "reference": "35810817c14d" - }, - "time": "2014-10-13 12:04:55", - "type": "library" - }, - "1.0.x-dev": { - "name": "bar/baz", - "version": "1.0.x-dev", - "version_normalized": "1.0.9999999.9999999-dev", - "source": { - "type": "hg", - "url": "http://some.where/over/the/rainbow/", - "reference": "ffff9aae6ed5" - }, - "time": "2014-10-13 12:05:37", - "type": "library" - }, - "dev-default": { - "name": "bar/baz", - "version": "dev-default", - "version_normalized": "9999999-dev", - "source": { - "type": "hg", - "url": "http://some.where/over/the/rainbow/", - "reference": "f317e556f2e2" - }, - "time": "2014-10-13 12:06:45", - "type": "library", - "extra": { - "branch-alias": { - "dev-default": "1.1.x-dev" - } - } - } - }, - "foo/bar": { - "1.0.0": { - "name": "foo/bar", - "version": "1.0.0", - "version_normalized": "1.0.0.0", - "source": { - "type": "hg", - "url": "http://some.where/over/the/rainbow/", - "reference": "249dec95a52a" - }, - "time": "2014-10-11 15:42:00", - "type": "library" - }, - "1.0.1": { - "name": "foo/bar", - "version": "1.0.1", - "version_normalized": "1.0.1.0", - "source": { - "type": "hg", - "url": "http://some.where/over/the/rainbow/", - "reference": "21e3328295d4" - }, - "time": "2014-10-11 15:45:56", - "type": "library" - }, - "1.0.x-dev": { - "name": "foo/bar", - "version": "1.0.x-dev", - "version_normalized": "1.0.9999999.9999999-dev", - "source": { - "type": "hg", - "url": "http://some.where/over/the/rainbow/", - "reference": "14dc17c8e860" - }, - "time": "2014-10-11 15:45:59", - "type": "library" - }, - "1.1.0": { - "name": "foo/bar", - "version": "1.1.0", - "version_normalized": "1.1.0.0", - "source": { - "type": "hg", - "url": "http://some.where/over/the/rainbow/", - "reference": "d2fa3e69ad5b" - }, - "require": { - "bar/baz": "~1.0" - }, - "time": "2014-10-11 15:43:16", - "type": "library" - }, - "dev-default": { - "name": "foo/bar", - "version": "dev-default", - "version_normalized": "9999999-dev", - "source": { - "type": "hg", - "url": "http://some.where/over/the/rainbow/", - "reference": "8e5a5c224336" - }, - "require": { - "bar/baz": "~1.0" - }, - "time": "2014-10-11 15:43:18", - "type": "library" - } - }, - "gar/nix": { - "1.0.0": { - "name": "gar/nix", - "version": "1.0.0", - "version_normalized": "1.0.0.0", - "source": { - "type": "hg", - "url": "http://some.where/over/the/rainbow/", - "reference": "44977145d64e" - }, - "time": "2014-10-13 12:03:33", - "type": "library" - }, - "dev-default": { - "name": "gar/nix", - "version": "dev-default", - "version_normalized": "9999999-dev", - "source": { - "type": "hg", - "url": "http://some.where/over/the/rainbow/", - "reference": "51cca95a31c2" - }, - "time": "2014-10-13 12:03:35", - "type": "library" - } - }, - "qux/quux": { - "dev-default": { - "name": "qux/quux", - "version": "dev-default", - "version_normalized": "9999999-dev", - "source": { - "type": "hg", - "url": "http://some.where/over/the/rainbow/", - "reference": "4a10a567baa5" - }, - "replace": { - "gar/nix": "1.0.*" - }, - "time": "2014-10-11 15:48:15", - "type": "library" - } - } - } -} diff --git a/doc/fixtures/repo-composer-with-includes/packages.json b/doc/fixtures/repo-composer-with-includes/packages.json deleted file mode 100644 index 1ef97530a..000000000 --- a/doc/fixtures/repo-composer-with-includes/packages.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "packages": [ - - ], - "includes": { - "include/all$5fa86b937f0502d92f776072cd49c002dca742b9.json": { - "sha1": "5fa86b937f0502d92f776072cd49c002dca742b9" - } - } -}