Below From: Gregg Reynolds [mailto:[email protected]] Sent: Tuesday, January 2, 2018 9:46 PM To: Dave Thaler <[email protected]> Cc: iotivity-dev <[email protected]> Subject: Re: [dev] Proposed API guidelines
On Aug 18, 2017 10:55 AM, "Dave Thaler via iotivity-dev" <[email protected]<mailto:[email protected]>> 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" [DT] Currently, the “out/” directory that’s created by a build. That’s where built files get placed. * 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? [DT] The binary- breaking changes guideline applies if shared libraries are built. That’s because the app is a separate binary and may be serviced/patched/updated separately from the shared library binary. For platforms that don’t build shared libraries, only static libraries, then it doesn’t matter. (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. [DT] Semantics. I consider it a breaking change to an API sitting in the git repo. 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. [DT] Some folks have argued to me in the past that all iotivity APIs were released as experimental, so your argument is that iotivity makes little sense to you. I’m not going to argue that point, I’m just dealing with current reality. And the fact that people keep needing to put in new APIs (for cloud, easy setup, etc.) that are not known whether the shape is good yet or not. 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. (more later…) 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 [email protected] https://lists.iotivity.org/mailman/listinfo/iotivity-dev
