[openstack-dev] [all] [api] API stability and change guidelines

Chris Dent cdent+os at anticdent.org
Wed Mar 15 12:22:10 UTC 2017

Short Version:

Please review "Refactor and re-validate api change guidelines"
https://review.openstack.org/#/c/421846/ this week because we
intend to freeze it next week and I've heard a lot of people
comment lots of places but not on the review.

Long Version:

At the PTG we had nearly a full day (Monday) of discussion about
guidelines for stability and change handling in APIs. Many of the
participants, especially in the morning, had very strong feelings
and opinions.

Since then the document has been lightly refined, but most of the
participation has been from people who might be described as already
in agreement [1] with the fundamental principles which are:

* effectively all change needs to be versioned
* the best tool we have right now for doing that versioning are
* all versions should be kept around as long as possible,
   potentially forever

I've been keeping the review open and lingering because I've been
hoping to get input from those people who disagree or have concerns
so that those issues are at least recorded on the review. Some of
the issues are centered around:

* general dislike of the microversion tech
* concerns about the degree of technical debt and backwards
   compatibility cruft that the guideline implies will need to be
* the way in which having such a guideline enables and even
   encourages deployments to never or rarely upgrade
* fears that such a guideline will be used as a whip against
   projects that want to fix things in way that violates them
* conversely, fears that such a guideline won't have sufficient
   teeth to drive projects towards consistency

If you share any of these concerns, please comment on the review
at https://review.openstack.org/#/c/421846/ so everyone involved can
know about it and we can have it in the record and hopefully make
the document more fully relevant as a result.

Thank you for participating.

[1] or at least accepting of as a useful compromise

Chris Dent                 ¯\_(ツ)_/¯           https://anticdent.org/
freenode: cdent                                         tw: @anticdent

More information about the OpenStack-dev mailing list