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://lists.iotivity.org/mailman/listinfo/iotivity-dev
