Updated docs with info about safe updates during install


From here: http://nuget.codeplex.com/workitem/1583

Documentation states that, for dependencies that are already installed:

"If the dependency is already installed, then one of two things happens:
  • If the installed dependency is within the version range, then nothing more needs to happen. The dependency is met.
  • If the installed dependency is outside of the version range, installation fails. (Version leveling in a future version of NuGet will fix this.)"
This doesn't seem to be the actual behavior, based on this:

PM> Install-Package Newtonsoft.Json -Version 4.0.2
Successfully installed 'Newtonsoft.Json 4.0.2'.
Successfully added 'Newtonsoft.Json 4.0.2' to Foo.Tests.ApiTests.

PM> Install-Package RestSharp -Version 101.3
Attempting to resolve dependency 'Newtonsoft.Json'.
Successfully installed 'Newtonsoft.Json 4.0.3'.
Successfully installed 'RestSharp 101.3'.
Successfully removed 'Newtonsoft.Json 4.0.2' from Foo.Tests.ApiTests.
Successfully added 'Newtonsoft.Json 4.0.3' to Foo.Tests.ApiTests.
Successfully added 'RestSharp 101.3' to Foo.Tests.ApiTests.
Successfully uninstalled 'Newtonsoft.Json 4.0.2'.

The dependency in RestSharp.nuspec does not have any particular version number.
<dependency id="Newtonsoft.Json" />

Ah, I think the docs are outdated. I think we do "safe" upgrades based on the semantics of SemVer, http://semver.org/. Assuming a version of X.Y.Z, Patch version Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior.

We figured you probably want bug fixes. Of course, not every package author follows this, but we're going to try and encourage it more and more. If the package author did break you, please contact them and tell them adding breaking changes without incrementing the Major (or at least Minor) version is not nice.

In the meanwhile, if you want to lock that version, you can by hand editing packages.config and adding an allowedVersions attribute with a version range. In your case:

<package id="NewtonSoft.Json" allowedVersion="[4.0.2]" />