Open Stack

Semantic versioning is bigger than just API changes. In fact, since we separately version the API, we can actually be quite explicit about what's in a particular release. In general, we do semantic versioning in Swift for a few reasons, but the main one is that it's been requested and confirmed by deployers as what they want at almost every OpenStack summit.


With the Swift 2.0 release, we did not change the Swift API version. The API is still "v1" (as it has been since OpenStack began). This API stability is something we work very hard to keep. Although we have added a few things to the API, we have not done anything that would prevent clients written to the Swift API 4+ years ago from working against master today. As Anne mentioned, the storage policies feature in Swift 2.0 has only added new headers to the API. That is, new clients can take advantage of the new features, but old clients can still speak the same protocol and still work (and even take advantage of storage policies in a limited way).

There are two main reasons we bumped the major version of Swift in this recent release from 1 to 2. First, and most importantly, if a deployer upgrades to this release and implements multiple storage policies, the deployer will not be able to downgrade and still access all of the data stored across all of the policies. Although it's still possible to upgrade to 2.0 and then roll the upgrade back before defining additional storage policies (and like always possible to upgrade with no downtime), we wanted to explicitly communicate the upgrade risk with a major version bump.

The second major reason we bumped the major version number in this release is because storage policies are such a big deal in the life of the project. This is a watershed feature in Swift, and the code changes required to implement it significantly impacted a large part of the code base. And from the user perspective, storage policies allow an enormous amount of flexibility in how the data is stored.

So to sum up, the Swift 2.0 release is a big deal in the life of the project. The major version number bump in the version number is intended to communicate that to deployers. The API is largely unaffected and existing clients still work; therefore the API version has been kept at v1.

Hope this helps clear things up.

--John






On Jul 22, 2014, at 10:05 AM, Shrinand Javadekar <shrinand at maginatics.com> wrote:

> This is confusing. So does this mean semantic versioning applies to
> the API's and not the Swift product versions? If so how are the
> product versions decided? And given a product version, how does one
> know about what API version is in use? The /info endpoint does not
> mention the API version.
> 
> I had asked about versioning sometime ago [1] and I thought the
> release version and API version are identical.
> 
> -Shri
> 
> [1] http://www.gossamer-threads.com/lists/openstack/dev/36042
> 
> 
> On Tue, Jul 22, 2014 at 5:37 AM, Anne Gentle <anne at openstack.org> wrote:
>> Hi Shri,
>> The Object Storage API change is just to add a header called
>> 'X-Storage-Policy: <name>' where name is set in the swift configuration
>> files by the cloud provider.
>> 
>> See http://docs.openstack.org/developer/swift/overview_policies.html
>> 
>> We'll add it to the API docs next, no version change needed for the API
>> itself.
>> Anne
>> 
>> 
>> On Tue, Jul 22, 2014 at 12:46 AM, Shrinand Javadekar
>> <shrinand at maginatics.com> wrote:
>>> 
>>> Hi,
>>> 
>>> Swift has been following the semantic versioning scheme. The fact that
>>> the product version changed from v1.x to v2.0 should suggest that the
>>> Swift APIs changed in this release.
>>> 
>>> I see that storage policies has been the biggest change in this
>>> release. Has that impacted the APIs?
>>> 
>>> Is there a document that lists exactly the API difference between v1.x and
>>> v2.0?
>>> 
>>> Thanks in advance.
>>> -Shri
>>> 
>>> _______________________________________________
>>> Mailing list:
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack
>>> Post to     : openstack at lists.openstack.org
>>> Unsubscribe :
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack
>> 
>> 
> 
> _______________________________________________
> Mailing list: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack
> Post to     : openstack at lists.openstack.org
> Unsubscribe : http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 801 bytes
Desc: Message signed with OpenPGP using GPGMail
URL: <http://lists.openstack.org/pipermail/openstack/attachments/20140722/4346badd/attachment.sig>