Open Stack

On Tue, 14 Oct 2014 09:45:44 -0400
Jay Pipes <jaypipes at gmail.com> wrote:

> On 10/14/2014 12:52 AM, Christopher Yeoh wrote:
> > On Mon, 13 Oct 2014 22:20:32 -0400
> > Jay Pipes <jaypipes at gmail.com> wrote:
> >
> >> On 10/13/2014 07:11 PM, Christopher Yeoh wrote:
> >>> On Mon, 13 Oct 2014 10:52:26 -0400
> > And whilst I don't have a problem with having some guidelines which
> > suggest a future standard for APIs, I don't think we should be
> > requiring any type of feature which has not yet been implemented in
> > at least one, preferably two openstack projects and released and
> > tested for a cycle. Eg standards should be lagging rather than
> > leading.
> 
> What about "features" in some of our APIs that are *not* preferable?
> For instance: API extensions.
> 
> I think we've seen where API extensions leads us. And it isn't
> pretty. Would you suggest we document what a Nova API extension or a
> Neutron API extension looks like and then propose, for instance, not
> to ever do it again in future APIs and instead use schema
> discoverability?

So if we had standards leading development rather than lagging in the
past then API extensions would have ended up in the standard because we
once thought they were a good idea.

Perhaps we should distinguish in the documentation between
recommendations (future looking) and standards (proven it works well
for us). The latter would be potentially enforced a lot more strictly
than the former.

In the case of extensions I think we should have a section documenting
why we think they're a bad idea and new projects certainly shouldn't
use them. But also give some advice around if they are used what
features they should have (eg version numbers!). Given the time that it
takes to make major API infrastructure changes it is inevitable that
there will be api extensions added in the short to medium term. Because
API development will not just stop while API infrastructure is improved.

> > I think it will be better in git (but we also need it in gerrit)
> > when it comes to resolving conflicts and after we've established a
> > decent document (eg when we have more content). I'm just looking to
> > make it as easy as possible for anyone to add any guidelines now.
> > Once we've actually got something to discuss then we use git/gerrit
> > with patches proposed to resolve conflicts within the document.
> 
> Of course it would be in Gerrit. I just put it up on GitHub first 
> because I can't just add a repo into the openstack/ code
> namespace... :)

I've submitted a patch to add an api-wg project using your repository
as the initial content for the git repository.

https://review.openstack.org/#/c/128466/

Regards,

Chris