Open Stack

Hey,

Context for others - Jay asked for feedback on some API change
guidelines which he and David have been working on. See here:

  http://etherpad.openstack.org/Hn8rKP7XgB

So ... kudos for kicking this off. I think it'll help a lot to get this
stuff written down - e.g. consistency in reviews and to give confidence
to users that we do care about API compat.

What you have looks like a good start, but I think it's going to take an
sustained effort to polish this off into something really useful for
reviewers in particular.

The guidelines themselves will probably only get us so far. What will
probably be more effective is expanding on examples of where we
considered and approved/rejected an incompatible change. If we got into
the habit of discussing such proposed changes on the list and then
documenting the conclusion as examples in the guidelines, I think we'd
be in great shape pretty quickly.

I've taken a stab at reworking most of the doc, but I don't think I've
changed it all that much. I think we're pretty well aligned. The main
thing I tried to was make it read like helpful advice for reviewers and
developers rather than a stringent set of "THOU SHALT NOT"
commandments :-)

Hope that helps,
Mark.