From 8b12e395094fb43b61dd9505a9071f331578b87f Mon Sep 17 00:00:00 2001 From: Rob Bast Date: Thu, 17 Dec 2015 09:34:16 +0100 Subject: [PATCH 1/5] initial document --- doc/articles/pitfalls.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 doc/articles/pitfalls.md diff --git a/doc/articles/pitfalls.md b/doc/articles/pitfalls.md new file mode 100644 index 000000000..87c44e75b --- /dev/null +++ b/doc/articles/pitfalls.md @@ -0,0 +1,24 @@ + + +# Pitfalls + +## I have a dependency which contains a "repositories" definition in its composer.json, but it seems to be ignored. + +The [`repositories`](04-schema.md#repositories) configuration property is defined as [root-only] +(04-schema.md#root-package). It is not inherited. You can read more about the reasons behind this in the "[why can't +composer load repositories recursively?](articles/why-can't-composer-load-repositories-recursively.md)" article. + +## I have locked a dependency to a specific commit but get unexpected results. + +While Composer supports locking dependencies to a specific commit using the `#commit-ref` syntax, there are certain +caveats that one should take into account. The most important one is [documented](04-schema.md#package-links), but +frequently overlooked: + +> **Note:** While this is convenient at times, it should not be how you use +> packages in the long term because it comes with a technical limitation. The +> composer.json metadata will still be read from the branch name you specify +> before the hash. Because of that in some cases it will not be a practical +> workaround, and you should always try to switch to tagged releases as soon +> as you can. From 04fb28a9cb21835c46bca45398de92f2ce9e2021 Mon Sep 17 00:00:00 2001 From: Rob Bast Date: Thu, 17 Dec 2015 14:13:37 +0100 Subject: [PATCH 2/5] add possible work-around / solution --- doc/articles/pitfalls.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/doc/articles/pitfalls.md b/doc/articles/pitfalls.md index 87c44e75b..b3bfde8f7 100644 --- a/doc/articles/pitfalls.md +++ b/doc/articles/pitfalls.md @@ -7,13 +7,15 @@ ## I have a dependency which contains a "repositories" definition in its composer.json, but it seems to be ignored. The [`repositories`](04-schema.md#repositories) configuration property is defined as [root-only] -(04-schema.md#root-package). It is not inherited. You can read more about the reasons behind this in the "[why can't +(04-schema.md#root-package). It is not inherited. You can read more about the reasons behind this in the "[why can't composer load repositories recursively?](articles/why-can't-composer-load-repositories-recursively.md)" article. +The simplest work-around to this limitation, is moving or duplicating the `repositories` definition to your root +composer.json. ## I have locked a dependency to a specific commit but get unexpected results. -While Composer supports locking dependencies to a specific commit using the `#commit-ref` syntax, there are certain -caveats that one should take into account. The most important one is [documented](04-schema.md#package-links), but +While Composer supports locking dependencies to a specific commit using the `#commit-ref` syntax, there are certain +caveats that one should take into account. The most important one is [documented](04-schema.md#package-links), but frequently overlooked: > **Note:** While this is convenient at times, it should not be how you use @@ -22,3 +24,5 @@ frequently overlooked: > before the hash. Because of that in some cases it will not be a practical > workaround, and you should always try to switch to tagged releases as soon > as you can. + +There is no simple work-around to this limitation. It is therefor strongly recommended that you do not use it. From aca19deffa1b441952996b201cf055bb6b0d60d5 Mon Sep 17 00:00:00 2001 From: Rob Bast Date: Mon, 11 Jan 2016 10:23:14 +0100 Subject: [PATCH 3/5] move to troubleshooting --- doc/articles/pitfalls.md | 28 ---------------------------- doc/articles/troubleshooting.md | 23 +++++++++++++++++++++++ 2 files changed, 23 insertions(+), 28 deletions(-) delete mode 100644 doc/articles/pitfalls.md diff --git a/doc/articles/pitfalls.md b/doc/articles/pitfalls.md deleted file mode 100644 index b3bfde8f7..000000000 --- a/doc/articles/pitfalls.md +++ /dev/null @@ -1,28 +0,0 @@ - - -# Pitfalls - -## I have a dependency which contains a "repositories" definition in its composer.json, but it seems to be ignored. - -The [`repositories`](04-schema.md#repositories) configuration property is defined as [root-only] -(04-schema.md#root-package). It is not inherited. You can read more about the reasons behind this in the "[why can't -composer load repositories recursively?](articles/why-can't-composer-load-repositories-recursively.md)" article. -The simplest work-around to this limitation, is moving or duplicating the `repositories` definition to your root -composer.json. - -## I have locked a dependency to a specific commit but get unexpected results. - -While Composer supports locking dependencies to a specific commit using the `#commit-ref` syntax, there are certain -caveats that one should take into account. The most important one is [documented](04-schema.md#package-links), but -frequently overlooked: - -> **Note:** While this is convenient at times, it should not be how you use -> packages in the long term because it comes with a technical limitation. The -> composer.json metadata will still be read from the branch name you specify -> before the hash. Because of that in some cases it will not be a practical -> workaround, and you should always try to switch to tagged releases as soon -> as you can. - -There is no simple work-around to this limitation. It is therefor strongly recommended that you do not use it. diff --git a/doc/articles/troubleshooting.md b/doc/articles/troubleshooting.md index c03395d61..ca62952b6 100644 --- a/doc/articles/troubleshooting.md +++ b/doc/articles/troubleshooting.md @@ -74,6 +74,29 @@ This is a list of common pitfalls on using Composer, and how to avoid them. checking out. Using this, the checkout will not be in detached state any more and cyclic dependency is recognized correctly. +## I have a dependency which contains a "repositories" definition in its composer.json, but it seems to be ignored. + +The [`repositories`](04-schema.md#repositories) configuration property is defined as [root-only] +(04-schema.md#root-package). It is not inherited. You can read more about the reasons behind this in the "[why can't +composer load repositories recursively?](articles/why-can't-composer-load-repositories-recursively.md)" article. +The simplest work-around to this limitation, is moving or duplicating the `repositories` definition to your root +composer.json. + +## I have locked a dependency to a specific commit but get unexpected results. + +While Composer supports locking dependencies to a specific commit using the `#commit-ref` syntax, there are certain +caveats that one should take into account. The most important one is [documented](04-schema.md#package-links), but +frequently overlooked: + +> **Note:** While this is convenient at times, it should not be how you use +> packages in the long term because it comes with a technical limitation. The +> composer.json metadata will still be read from the branch name you specify +> before the hash. Because of that in some cases it will not be a practical +> workaround, and you should always try to switch to tagged releases as soon +> as you can. + +There is no simple work-around to this limitation. It is therefor strongly recommended that you do not use it. + ## Need to override a package version Let's say your project depends on package A, which in turn depends on a specific From 8cc50f9c8b91da0be79005cfb8a3536fa22c0642 Mon Sep 17 00:00:00 2001 From: Rob Bast Date: Tue, 12 Jan 2016 08:47:11 +0100 Subject: [PATCH 4/5] minor tweaking of phrasing --- doc/articles/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/articles/troubleshooting.md b/doc/articles/troubleshooting.md index ca62952b6..c6da624ad 100644 --- a/doc/articles/troubleshooting.md +++ b/doc/articles/troubleshooting.md @@ -79,7 +79,7 @@ This is a list of common pitfalls on using Composer, and how to avoid them. The [`repositories`](04-schema.md#repositories) configuration property is defined as [root-only] (04-schema.md#root-package). It is not inherited. You can read more about the reasons behind this in the "[why can't composer load repositories recursively?](articles/why-can't-composer-load-repositories-recursively.md)" article. -The simplest work-around to this limitation, is moving or duplicating the `repositories` definition to your root +The simplest work-around to this limitation, is moving or duplicating the `repositories` definition into your root composer.json. ## I have locked a dependency to a specific commit but get unexpected results. From a927499bd57e1933160ee4d42f81eaba3e999bf9 Mon Sep 17 00:00:00 2001 From: Rob Bast Date: Tue, 19 Jan 2016 15:12:46 +0100 Subject: [PATCH 5/5] fix typo --- doc/articles/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/articles/troubleshooting.md b/doc/articles/troubleshooting.md index c6da624ad..3edc793ba 100644 --- a/doc/articles/troubleshooting.md +++ b/doc/articles/troubleshooting.md @@ -95,7 +95,7 @@ frequently overlooked: > workaround, and you should always try to switch to tagged releases as soon > as you can. -There is no simple work-around to this limitation. It is therefor strongly recommended that you do not use it. +There is no simple work-around to this limitation. It is therefore strongly recommended that you do not use it. ## Need to override a package version