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:[email protected]] 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%7CDaniel.Mihai%40microsoft.com%7C038dfeaf6cd844628d2c08d47bb6bbc2%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636269472151475201&sdata=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.iotivity.org%2Fmailman%2Flistinfo%2Fiotivity-dev&data=02%7C01%7CDaniel.Mihai%40microsoft.com%7C038dfeaf6cd844628d2c08d47bb6bbc2%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636269472151475201&sdata=LPFrqVu5nyw2xby%2FkNxSZ7Z7ad9vsnL%2BdyUbP7Pvwy8%3D&reserved=0
