Open Stack

+1 to the reasoning and position taken. Nicely put.

Chris

Sent from my iPad

On Jul 25, 2012, at 12:51 PM, "Mark McLoughlin" <markmc at redhat.com> wrote:

> Hey,
>
> Trying to get away from this specific issue for a minute ... some
> points:
>
>    - We fix bugs all the time that may affect clients which rely on the
>      specific buggy behaviour. Not just pure API changes like this one,
>      but subtle behavioural changes.
>
>    - API compatibility is very important. As a general rule, we don't
>      want to break clients.
>
>    - If we take things to extremes and wait until the next major
>      version to fix *any* issue which *may* have an impact on clients,
>      I don't think anyone will thank us.
>
>    - So, there's a client impact threshold under which we accept the
>      bugfixes without a major version bump.
>
>    - What that threshold is will partly depend on when the next major
>      version will be - e.g. if v3 will be in 5 years time, it wouldn't
>      be sane for us to wait that long to fix issues which have minimal
>      client impact.
>
>    - We certainly do want to get to a point where we can make a
>      commitment to not make changes even this minor, but I don't think
>      the project is there yet.
>
>    - Our API documentation doesn't cover every aspect of the API which
>      clients may come to rely on. We also don't really document what
>      clients should avoid relying on (e.g. URL structure, specific
>      response codes etc.) so we can't always rely on the documentation
>      to tell us whether an API fix is acceptable.
>
>    - I hate to think of us rejecting API fixes with "this needs to wait
>      until v3" and then, when v3 comes around, we don't actually get
>      around to fixing those issues. We need some way of channelling
>      people's desire to fix the API, even if that's just helping to
>      document what needs fixing in v3.
>
> So, thinking about this specific issue:
>
>    - "201 Created" is clearly the right behaviour and is what we do
>      elsewhere in the API. Unfortunately, we don't document this so we
>      can't just say "see, we're just making it compliant with the spec".
>
>    - Some clients may be relying on "200 OK" and they may be affected
>      by this change. However, more sensible clients would just accept
>      any 2xx code as success. In terms of impact that I expect API
>      clients may see between Essex and Folsom, my guess is this is
>      pretty minor.
>
>    - I don't know of any plans for v3. I also don't know that we have
>      any way to channel this effort into preparing for v3.
>
> No-one reading this should interpret it as a lack of understanding of
> the importance of API compatibility. There is a spectrum of API compat
> strictness. Where we fall on the spectrum at this point of the project's
> life isn't a trivial question. We don't want to be at either of the
> extreme ends of the spectrum (e.g. the rules Sun used to apply to
> Solaris changes vs Ruby libraries which change API every day of the
> week), so please don't try and make out this is a black-and-white thing.
>
> Cheers,
> Mark.
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20120725/c89c2646/attachment-0001.html>