I like this proposal. It's consistent with the current platform support guidelines, and it adds a way to clearly delineate experimental APIs. I also think it's complementary to Mats's suggestions of how to annotate experimental APIs.
I have no preference between the term "experimental" vs "preview" though. I say that because there may be some people that prefer the term "preview" instead. Dave > -----Original Message----- > From: Daniel Mihai > Sent: Thursday, April 6, 2017 12:09 PM > To: Mats Wichmann <mats at wichmann.us>; Dave Thaler > <dthaler at microsoft.com>; uzchoi at samsung.com > Cc: iotivity-dev at lists.iotivity.org; 'Wouter van der Beek (wovander)' > <wovander at cisco.com> > Subject: Public and Experimental Public C APIs > > Should we start with the following definitions? > > 1. All C functions included under out/<path_to_IoTivity_SDK>/ are Public > APIs > 2. All C functions included under out/<path_to_IoTivity_SDK>/experimental/ > are Experimental Public APIs > 3. When an Experimental Public API gets promoted to non-Experimental > Public API, that API SHALL be moved out of > out/<path_to_IoTivity_SDK>/experimental/ header files > 4. Apps should expect potential breaking changes to Experimental Public > APIs, but no breaking changes to non-Experimental Public APIs > > BTW, a couple of days ago I said that we were not even close to ready to lock > down the Public APIs. Since then, I've learned that all or most of the > problematic APIs that I had in mind are not yet under > out/<path_to_IoTivity_SDK>/. Given that additional information, and if we > apply the definitions I proposed above, locking down the current non- > Experimental Public API sounds a lot more reasonable to me. We still get the > chance to improve the problematic APIs, before they become non- > Experimental Public APIs. > > Thanks, > Dan > > -----Original Message----- > From: iotivity-dev-bounces at lists.iotivity.org [mailto:iotivity-dev- > bounces at lists.iotivity.org] On Behalf Of Mats Wichmann > Sent: Tuesday, April 4, 2017 5:00 PM > To: Dave Thaler <dthaler at microsoft.com> > Cc: iotivity-dev at lists.iotivity.org > Subject: Re: [dev] Don't make breaking changes > > On 04/04/2017 03:25 PM, Mats Wichmann wrote: > > > It's not that hard to add your own definitions to the Doxyfile. > > I ended up using some html, but cleaner approaches might be possible: > > https://na01.safelinks.protection.outlook.com/?url=http:%2F%2Fwww.stack > .nl%2F~dimitri%2Fdoxygen%2Fmanual%2Fcustcmd.html&data=02%7C01%7C > Daniel.Mihai%40microsoft.com%7C038dfeaf6cd844628d2c08d47bb6bbc2%7C > 72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636269472151475201&sda > ta=xpxhfRX60H7ZGau1iXxjHqZ8zVM0qkFFSflrxtri5So%3D&reserved=0 > > anyway, I agreed with the comment that it's not great for a developer if > some stuff in a header is fine and other stuff is experimental. Better > if we could section it, though depending on the scale of the feature > that may not be easy. > > Indeed, none of this is terribly easy, it's a maturity thing and much as > we'd like to think otherwise, from the app-developer viewpoint, iotivity > isn't really that mature. To be balanced, it's way better on the device > side, as there what's interesting is "does it respond to the OIC/OCF > protocol correctly", and we can actually answer and track that question > with some degree of confidence through the CTT and other tests. > _______________________________________________ > iotivity-dev mailing list > iotivity-dev at lists.iotivity.org > https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Flists.io > tivity.org%2Fmailman%2Flistinfo%2Fiotivity- > dev&data=02%7C01%7CDaniel.Mihai%40microsoft.com%7C038dfeaf6cd8446 > 28d2c08d47bb6bbc2%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C6 > 36269472151475201&sdata=LPFrqVu5nyw2xby%2FkNxSZ7Z7ad9vsnL%2BdyU > bP7Pvwy8%3D&reserved=0
