[openstack-dev] API changes [was: Re: [API] Standardizing status codes in the native API]

David Kranz david.kranz at qrclab.com
Fri Jul 27 13:26:40 UTC 2012


Go for it. You will see that we split it into two, one for guidelines 
and one for policy.

http://wiki.openstack.org/Governance/Proposed/APIStabilityand 
http://wiki.openstack.org/APIChangeGuidelines

  -David

On 7/27/2012 8:57 AM, Anne Gentle wrote:
> 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
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev




More information about the OpenStack-dev mailing list