Open Stack

Thanks, Mark. I agree with your sentiments and your improvements to the 
document. I was trying to get my thoughts down as quickly as possible 
and it was a bit terse :-) . It now looks more like something that is 
presentable as a set of guidelines and rationales.

I also agree about citing examples as a good way to clarify things. I 
have been down this road before and am optimistic that once everybody  
understands the details, thinking about them will become second nature.

  -David


On 7/25/2012 6:03 PM, Mark McLoughlin wrote:
> 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.
>