On Wed, Jan 3, 2018 at 3:36 PM, Nash, George <[email protected]> wrote:
> > The whole concept of "experimental API" makes little sense to me. > "Release with experimental (i.e. non-production) APIs" strikes me as an > oxymoron. > > > > > We have branches for this kind of stuff. General rule: nothing goes into > a release that is not production-quality and officially supported. > Otherwise what is the point of having releases at all, instead of mere tags? > > > 1.3 Internal APIs > > The theory behind experimental API is not a hard to understand as you may > think. It is code that has been developed and is intended to be > production-quality. Maybe the branch did not attract much attention or > could benefit from more eyes looking at the code. Till it is merge with > master it will not get the attention of the community. It is a way to > introduce code that is believed to be ready for release but due to > circumstances the developers want to leave it open to API breaking changes > if something is discovered that was missed. A way to think of it would be a > public beta for the code in question. > > > Thanks, but trust me when I say I do not have a difficult time understanding the "experimental API" idea. I just think it is a (very) bad idea. It's not like introducing new code is an innovation. If you could point out a well-known, successful open source project that has anything remotely like "experimental API" I would be grateful; I've never seen anything like it. For the (many) open source projects I've looked at issuing a release with stuff that is non-releasable makes no sense. > > > > APIs can be deprecated by marking them as @deprecated. The associated > text should explain > > > what an application should do instead. Public APIs must be @deprecated > for at least two > > > releases before they can be removed. The reasons for deprecation of > APIs should be discussed > > > on the iotivity-dev list. > > > > Along with the @depricated doxygen tag, I have been trying to introduce an > OC_DEPRECATED macro that can be used in C and C++ code to add compiler > specific keywords so the compiler will tell the user of the code they are > using deprecated functions/classes via compiler warnings. > Might be less of a hassle to just list the deprecated stuff in a separate file. I think it should be the responsibility of the developer to avoid deprecated stuff, so long as it is properly documented and publicized. Deprecated does not mean illegal; devs are free to use deprecated stuff if they are willing to take the risk that their code may later break. I'm not against the macros you're suggesting, I just think the time might be better spent on other things. g
_______________________________________________ iotivity-dev mailing list [email protected] https://lists.iotivity.org/mailman/listinfo/iotivity-dev
