From a09959173513da3c15ce070ef53c72ab9b62dfb1 Mon Sep 17 00:00:00 2001 From: Jordi Boggiano Date: Wed, 9 Apr 2014 14:46:32 +0200 Subject: [PATCH] Adjustments to unbound constraint docs --- ...-unbound-version-constraints-a-bad-idea.md | 34 +++++++------------ 1 file changed, 13 insertions(+), 21 deletions(-) diff --git a/doc/faqs/why-are-unbound-version-constraints-a-bad-idea.md b/doc/faqs/why-are-unbound-version-constraints-a-bad-idea.md index a85bf35f6..ac9cfa79b 100644 --- a/doc/faqs/why-are-unbound-version-constraints-a-bad-idea.md +++ b/doc/faqs/why-are-unbound-version-constraints-a-bad-idea.md @@ -1,29 +1,21 @@ # Why are unbound version constraints a bad idea? -A version constraint without an upper bound will allow any future version of -the dependency, even newer major version breaking backward compatibility -(which is the only reason to bump the major version when following semver). +A version constraint without an upper bound such as `*` or `>=3.4` will allow +updates to any future version of the dependency. This includes major versions +breaking backward compatibility. Once a release of your package is tagged, you cannot tweak its dependencies -anymore in case a dependency breaks BC (you have to do a new release but the -previous one stays broken). +anymore in case a dependency breaks BC - you have to do a new release but the +previous one stays broken. -These leaves you with 3 alternatives to avoid having broken releases: +The only good alternative is to define an upper bound on your constraints, +which you can increase in a new release after testing that your package is +compatible with the new major version of your dependency. -- defining an upper bound on your constraint (which you will increase in a - new release after testing that your package is compatible with the new - version) +For example instead of using `>=3.4` you should use `~3.4` which allows all +versions up to `3.999` but does not include `4.0` and above. The `~` operator +works very well with libraries follow [semantic versioning](http://semver.org). -- knowing all future changes of your dependency to guarantee the compatibility - of the current code. Forget this alternative unless you are Chuck Norris :) - -- never release your package, but this means that all users will have to - whitelist the dev versions to install it (and complain about it) - -The recommended way is of course to define an upper bound on your constraint, -so Composer will show you a warning for unbound constraints when validating -your `composer.json` file. - -As a package maintainer, you can make the life of your users easier by -providing an [alias version](../articles/aliases.md) for your development +**Note:** As a package maintainer, you can make the life of your users easier +by providing an [alias version](../articles/aliases.md) for your development branch to allow it to match bound constraints.