Dave, those guidelines look pretty good to me. Additional thoughts: a. All new Public API names start with “OC” b. All Experimental API names start with “OCX” c. When an “OCX” API is ready to become an “OC” API, that API is renamed accordingly. d. Renaming the API ensures that all callers get a chance to notice the transition from Experimental to Public status, to review the new Public API and to adapt to possible changes in behavior of that API.
Mats said: >> 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. I believe I discussed with Dave a while back one way to help with this kind of compatibility problem: the behavior of the old test should never change. IoTivity would add new tests, for the new behavior, but continue to test the old behavior too. Dan From: [email protected] <[email protected]> on behalf of Mats Wichmann <[email protected]> Sent: Friday, August 18, 2017 9:34 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%7CDaniel.Mihai%40microsoft.com%7C2afc59a9329b49a27f1508d4e6570bf7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636386708934811987&sdata=VSDzmJzoGglmKtQHnK4uVodj2W2laPhrwcDtD29e938%3D&reserved=0 _______________________________________________ iotivity-dev mailing list [email protected] https://lists.iotivity.org/mailman/listinfo/iotivity-dev
