Open Stack

David, thanks for the write up.

In the case of "the existing API is not documented" I'd like the
policy to reflect the importance of documenting any changes to the API
when they're made as well as retroactively. Can I take a stab at
editing?

Thanks,
Anne

On Thu, Jul 26, 2012 at 3:51 PM, David Kranz <david.kranz at qrclab.com> wrote:
> In order to let interested people subscribe to and more easily follow
> changes to this document I have moved it to
>
> http://wiki.openstack.org/Governance/Proposed/Policy%20for%20Changes%20to%20OpenStack%20APIs
>
> Please make comments/edits there. After a few more days (or sooner) it would
> be good to post this on the
> general mailing list as well since I am sure non-developers will be
> interested.
>
>  -David
>
>
> On 7/26/2012 4:43 AM, Eoghan Glynn wrote:
>>>
>>> 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.
>>
>> Agreed, the current version on etherpad is a *great* start, and will be
>> an excellent resource if we continue to codify the group wisdom as it
>> evolves.
>>
>> Just one suggestion, can we put the guidelines under version control,
>> in the style of the HACKING.rst?
>>
>> So, I've just added a small clarification to the etherpad, and there's
>> nothing to stop anyone else adding their particular slant, without it
>> necessarily reflecting the group consensus.
>>
>> Whereas putting the thing in git at least ensures some oversight on
>> changes. Obviously the guideline should apply across all projects, but
>> I think it would be OK to just stick the file into the nova repo
>> (with the understanding that there's broader applicability).
>>
>> Thanks,
>> Eoghan
>>
>>> 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.
>>>
>>>
>>> _______________________________________________
>>> OpenStack-dev mailing list
>>> OpenStack-dev at lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>>
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev