deltacloud-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Lutterkort <lut...@redhat.com>
Subject Re: Tracking API changes more tightly
Date Wed, 30 Jan 2013 16:41:54 GMT
On Tue, 2013-01-29 at 12:26 -0500, Chip Childers wrote:
> On Mon, Jan 28, 2013 at 5:31 PM, David Lutterkort <lutter@redhat.com> wrote:
> > We should try and track changes that affect the user-visible API more
> > tightly. To make this possible, I suggest we put into the commit message
> > (not the title line of the commit) a tag 'API-Change (CIMI|DC|EC2): ...'
> >
> > For example, for a commit that makes a change to the DC API:
> >
> >         Indicate behavior of root device for Image and HWP
> >
> >         .. more text about the commit ..
> >
> >         API-Change (DC): add root_type attribute to image and HWP
> >
> > That makes it possible to find such changes with 'git-log
> > --grep=API-Change'
> >
> > David
> 
> Forgive my uneducated questions...  but here they are:
> 
> Would the intent be to coalesce the resulting changes into each
> release's NEWS file during the release process?

Yes, that's one of the reasons to do this; at some point we might also
need to throw something along these lines on the website.

> Does Deltacloud use semver?  If so, does it consider the DC API to be
> the focus of the backward compatibility for major version number
> changes?

For the DC frontend, we follow the general notion of RESTful backwards
compatibility: clients are supposed to ignore anything in responses they
do not know about, in exchange we promise to never break anything that
works now. For the gory details behind that thinking see [1]

If we'd ever need to break backwards compat, we would probably do that
by introducing a new entrypoint, say /api2 vs /api.

David

[1] http://watzmann.net/blog/2012/08/rest-api-evolution.html


Mime
View raw message