Two new proposed API guidelines, please review: * A public API should not be added to Iotivity if there is already a non-deprecated API that can just as easily be used (i.e., with approximately the same number of lines of code).
* A public API should not be added to Iotivity if the API would provide generic functionality (i.e., not inherently OCF or Iotivity specific functionality) that could be provided by an external library. I think the same two guidelines would also apply to experimental APIs. Dave -----Original Message----- From: [email protected] [mailto:[email protected]] On Behalf Of Mats Wichmann Sent: Friday, August 18, 2017 9:35 AM To: [email protected] Subject: Re: [dev] Proposed API guidelines On 08/18/2017 09:54 AM, Dave Thaler via iotivity-dev 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.3 Internal APIs > ----------------- > Internal APIs are considered to be usable within IoTivity but are not > intended to be used by applications that use IoTivity. shall not. I'd anticipate if we ever end up with an API checker, running it against an app that uses an internal API would result in a FAIL report. I'm assuming it's not at the moment feasible to technically enforce that linking a (public) app against a private API fails (and maybe not even desirable, since there are test case binaries that will may to do so). > Internal API requirements: > * Internal APIs must not appear in any header file that is published to > the build directory > * Internal APIs should ideally be documented using doxygen markup in the > private header files > * Internal APIs must not be used in sample code > * 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. > 2 Programming Languages > ----------------------- > There may be multiple programming languages supported (whether publically or > experimentally). > The API maintainer may have a separate sub-maintainer per programming > language. Is there any intent to have a similarity (or even equivalence) of APIs across languages? > 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. > * Experimental and internal APIs can have breaking changes across > releases. I assume there will be APIs that will evolve, but use known API techniques to do so without breaking (versioning, perhaps; extending the meaning of an argument; etc.) How do we validate that changes don't break existing code? As a developer evolves an API, they will need to evolve the unit tests, proper TDD means the new test will pass with the new functionality - but now it's no longer the test that was used for the earlier version. > 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. Will need to define what "release" means in this context to avoid ambiguity. That is, is 1.3 + 1.3.1 two releases? If so, would one be able to drop a feature in 1.3.2 that was deprecated in 1.3(.0)? There's a little bit of a testing policy question that's not directly an API issue but maybe we should talk about: should tests be White Box tests (may know internals), Black Box tests (does not know internals), or more likely both? That is, for a particular chunk of code that exposes public APIs, do we want to require both a black-box test which specifically validates the behavior of the public API, and a separate white-box test that digs into the overall correctness of the subsystem, using internals where needed to do so? _______________________________________________ iotivity-dev mailing list [email protected] https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Flists.iotivity.org%2Fmailman%2Flistinfo%2Fiotivity-dev&data=02%7C01%7Cdthaler%40microsoft.com%7C2afc59a9329b49a27f1508d4e6570bf7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636386708947155806&sdata=f6Z9HvL%2BfWXlmiiN5xuzjn0Q7bE%2BUg04vsQqSfSvLXM%3D&reserved=0 _______________________________________________ iotivity-dev mailing list [email protected] https://lists.iotivity.org/mailman/listinfo/iotivity-dev
