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: [email protected] [mailto:[email protected]] On Behalf Of Rob Hoes Sent: 07 May 2010 14:26 To: '[email protected]' 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
_______________________________________________ xen-api mailing list [email protected] http://lists.xensource.com/mailman/listinfo/xen-api
