From 9d922331021a66c7b1604d0371bcfb319dde0a0b Mon Sep 17 00:00:00 2001 From: Max Lincoln Date: Tue, 22 Oct 2013 18:49:45 -0200 Subject: [PATCH] Semantic Versioning (and Pessimistic Versioning Constraint) notice I noticed some projects using Fog are setting very specific versioning constraint. For example, https://github.com/mitchellh/vagrant-rackspace/issues/34 happened because both vagrant-aws and vagrant-rackspace are using 3 digits of precision. The fog RELEASE.md says that Fog follows semantic versioning. Several other projects have put up notices suggesting to use 2 digits of precision for projects that follow semver. See https://github.com/intridea/multi_json, for example. I added a similar notice, but softened the language because I don't think there is a clear understanding on what semantic versioning means for a project like Fog, which has multiple providers backed by services that are all evolving at their own pace. --- README.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/README.md b/README.md index e4aab413c..73a2722b9 100644 --- a/README.md +++ b/README.md @@ -135,6 +135,31 @@ for more details and examples. Once you are ready to start scripting fog, here i geemus says: "That should give you everything you need to get started, but let me know if there is anything I can do to help!" +## Versioning + +Fog library aims to adhere to [Semantic Versioning 2.0.0][semver], although it does not +address challenges of multi-provider libraries. Semantic versioning is only guaranteed for +the common API, not any provider-specific extensions. You may also need to update your +configuration from time to time (even between Fog releases) as providers update or deprecate +services. + +However, we still aim for forwards compatibility within Fog major versions. As a result of this policy, you can (and +should) specify a dependency on this gem using the [Pessimistic Version +Constraint][pvc] with two digits of precision. For example: + +```ruby +spec.add_dependency 'fog', '~> 1.0' +``` + +This means your project is compatible with Fog 1.0 up until 2.0. You can also set a higher minimum version: + +```ruby +spec.add_dependency 'fog', '~> 1.16' +``` + +[semver]: http://semver.org/ +[pvc]: http://guides.rubygems.org/patterns/ + ## Contributing * Find something you would like to work on.