Hi Rob,
This document looks great, and I’m
sure will prove to be a big step forward.
I have a few comments about
areas in which I think the policy could helpfully be clarified a little better:
1.
You say that an
element in the “prototype” state is just a “stub” that
is not yet fully implemented. I’m not sure that this is always
appropriate. What about having a prototype that is fully implemented but not
yet ready to be fully supported, perhaps because it is an experimental feature?
2.
Into which state(s)
can a new API element enter? Must they all start as a prototype in a distinct
step or can they go straight into the “published” state?
3.
How are prototypes
removed? Can they go straight to the “removed” state or must they
first be “deprecated”?
4.
I think it could be
clarified when lifecycle transitions can happen. Section 4 discusses what
happens on releases, but it’s ambiguous whether transitions can also
happen between releases, in the unstable branch. For example, it might be
reasonable to state that transitions 3, 4 and 5 can only happen at a release
but 1 and 2 can happen at any time?
5.
I think it’s
worth explicitly talking about the policy for fields that are maps (typically
string->string maps). Is the set of keys similarly controlled?
6.
Traditionally, the
other-config field on various objects has been used for prototypes or
unsupported features. Will this continue?
Sorry, that’s rather a lot
of questions and not many suggested answers. I hope that it’s helpful
nonetheless.
Thanks for your efforts,
Jonathan
From:
xen-api-bounces@xxxxxxxxxxxxxxxxxxx
[mailto:xen-api-bounces@xxxxxxxxxxxxxxxxxxx] On Behalf Of Rob Hoes
Sent: 07 May 2010 14:26
To: 'xen-api@xxxxxxxxxxxxxxxxxxx'
Subject: [Xen-API] API evolution
Hi all,
Following the changeset related to the
API Evolution document I just submitted. This is an update to the document that
Dave Scott started a few weeks ago. A PDF is attached.
The intention is to agree on the best
way to evolve the XenAPI from release to release. Especially now the API is
becoming mature, and is used by more and more people, it is important to make
clear what exactly is part of the XenAPI, how things may change over time, how
we announce changes in terms of release notes, and what sort of compatibility
guarantees can be made.
The attached document is an initial
proposal that would benefit from a good discussion, especially on the topic of
compatibility. I’d like to invite everyone who has ideas or experiences
related to this to share these.
Thanks!
Rob
