Gregg wrote: 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?
[DT] The master vs. separate-branch discussion is certainly relevant here and worth having. Historically, iotivity culture has been to throw in all kinds of extra features and APIs (e.g., cloud support). If you’d like to argue that such features should not be in the master branch until they are production quality (including using only APIs that only meet the public API requirements), that’s a fine discussion for the list here, and not specific to APIs so wider than just what I as API maintainer would cover. More below… From: Nash, George [mailto:george.n...@intel.com] Sent: Wednesday, January 3, 2018 1:37 PM To: Gregg Reynolds <d...@mobileink.com>; Dave Thaler <dtha...@microsoft.com> Cc: iotivity-dev <iotivity-dev@lists.iotivity.org> Subject: RE: [dev] Proposed API guidelines > 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. Some OSS projects have separate STABLE vs BETA releases for this distinction. Using George’s definition above, all iotivity releases would be BETA releases and none are STABLE releases. Splitting APIs into public vs experimental means the same release can have both STABLE and BETA APIs in the same release, to distinguish them. That helps with that issue, but does not help with the issue of underlying features that might be BETA quality features that might affect STABLE features. > 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. https://gerrit.iotivity.org/gerrit/#/c/23111/<https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgerrit.iotivity.org%2Fgerrit%2F%23%2Fc%2F23111%2F&data=02%7C01%7Cdthaler%40microsoft.com%7Caea19bc778ec4c10a44208d552f20f5d%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C1%7C636506121968890185&sdata=QEZNcuzsrSYPEKplaRMUJVZUh%2B%2Be6lzkil9AIImQiHY%3D&reserved=0> example: I want to deprecate function `void foo()` I would write the following: /** @depricated foo has been deprecated due to security problems. Please use bar(). See IOT-1234 for more information /* OC_DEPRICATED( void foo(), 2018.01); Or /** @depricated foo has been deprecated due to security problems. Please use bar(). See IOT-1234 for more information /* OC_DEPRICATED_MSG( void foo(), “foo has been deprecated due to security problems. Please use bar(). See IOT-1234 for more information”, 2018.01); All good except that DEPRICATED is misspelled… should be OC_DEPRECATED (no I). What you show is what was done in the AllJoyn code base if I remember correctly, and I’m fine with doing the same in the iotivity code base. From: iotivity-dev-boun...@lists.iotivity.org<mailto:iotivity-dev-boun...@lists.iotivity.org> [mailto:iotivity-dev-boun...@lists.iotivity.org] On Behalf Of Gregg Reynolds Sent: Tuesday, January 2, 2018 9:46 PM To: Dave Thaler <dtha...@microsoft.com<mailto:dtha...@microsoft.com>> Cc: iotivity-dev <iotivity-dev@lists.iotivity.org<mailto:iotivity-dev@lists.iotivity.org>> Subject: Re: [dev] Proposed API guidelines On Aug 18, 2017 10:55 AM, "Dave Thaler via iotivity-dev" <iotivity-dev@lists.iotivity.org<mailto:iotivity-dev@lists.iotivity.org>> wrote: As the new API maintainer, here’s a set of proposed API guidelines. Please review so and feedback can be incorporated before making official guidelines. 1 APIs ------ There are three types of APIs: 1) Public 2) Experimental 3) Internal 1.1 Public APIs --------------- Public APIs are considered to be the supported APIs that apps can and should use. Public API requirements: * All public APIs must have at least one test case Check * All public APIs must be in a header file that is published to the build directory Define "build directory" * All public APIs must be fully documented using doxygen markup in the public header files Check * All public APIs must be used in some sample code or snippet Ideally, the sample should be one that is compiled as part of the build. For rarely used APIs, the sample might simply be a snippet in the doxygen comments. Close enough. * Public APIs cannot have source- or binary- breaking changes across IoTivity versions Source: check. I'm not so sure about binary. For example struct padding should be considered an implementation detail (?). More generally we should not make any guarantees not warranted by the (C, IMHO) language definition. ABIs are a different aminal. How are you going to verify binary compatibility for all compilers on all platforms? (Breaking changes can be made to a new API only until it is released for the first time.) Redundant. If it is not released, then it is not a breaking change. 1.2 Experimental APIs --------------------- 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 ----------------- Internal APIs are considered to be usable within IoTivity but are not intended to be used by applications that use IoTivity. Check. Internal API requirements: * Internal APIs must not appear in any header file that is published to the build directory See above. I guess you mean publicly exposed include directory? * Internal APIs should ideally be documented using doxygen markup in the private header files Check * Internal APIs must not be used in sample code Check * Internal APIs must not be used by any apps other than test code. For example, this means that sample provisioning apps must not use internal APIs. "not be used by any official sample apps..' 2 Programming Languages Suggest: "Language Bindings" ----------------------- There may be multiple programming languages supported (whether publically or experimentally). The API maintainer may have a separate sub-maintainer per programming language. I'm not sure you want to get into that unless you want to define an abstract Iotivity API (like DOM). After all anybody can implement a language binding in any way they see fit. The project could adopt a few "official" bindings (Java, JavaScript) but that's a lot of work, and you also do not want to discourage innovation. 3 Breaking Changes ------------------ The API maintainer shall be responsible for API breaking change policy. The proposed policy is: * Public APIs cannot have source- or binary- breaking changes across releases, except as covered by deprecation as explained below. API additions can be made at any time. See above note regarding binary compatibility. * Experimental and internal APIs can have breaking changes across releases. 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. Check 4 Gerrit review --------------- All changes that affect any public API header must include the API maintainer and/or appropriate language-specific sub-maintainers as code reviewers. The (sub)maintainers are responsible for ensuring that the above guidelines are met, and also reviewing the doxygen documentation for completeness and clarity. Check Implementers are encouraged to discuss the proposed APIs on the iotivity-dev list before they are implemented, since changes are typically much more costly after the APIs are implemented. Check Please send feedback to the list. Check. ;) Gregg
_______________________________________________ iotivity-dev mailing list iotivity-dev@lists.iotivity.org https://lists.iotivity.org/mailman/listinfo/iotivity-dev