On Wed, Jan 3, 2018 at 3:49 PM, Dave Thaler <[email protected]> wrote:
> 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]> 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. > Ok, so add "no other header files will be published to the build directory" or similar. It's been a while since I looked by my recollection is pretty much everything gets dumped into the "out/" dir structure. Maybe it would be better to stipulate that the result of a build will be some binaries in directory foo (e.g. lib/) and some (preferably one) headers in directory bar (e.g. include/). > > > * 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. > Sorry, I'm not seeing this. Maybe I don't understand what you mean. For example, suppose we have a struct. Client code should not make assumptions about binary layout. We could change the binary structure of the struct - add some padding or whatever - and it should still work. If client code makes assumptions about the binary structure of the struct, it loses - the C language makes no assurances about that. An app that makes assumptions about the binary structures of a lib should be expected to break, sometimes. C99: "12 Each non-bit-field member of a structure or union object is aligned in an implementation- defined manner appropriate to its type." Keywords: implementation-defined. I don't see how you can guarantee binary compatibility, but then that could be because I'm not smart enough. > > (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. > Well, yes, a "released" library that makes no promises about the API makes little sense to me. A good way to kill a project is to keep changing the API, or to make it hard to understand what the API is (e.g. by continually dumping new/experimental stuff into it). > 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. > Those things are not core OCF. And "needing to put" is in the eye of the beholder. It's one thing to maintain a core API (primitives) for a library; it's a whole 'nother thing to try to allow people/companies to just dump whatever they like into it. 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…) > Yep -g
_______________________________________________ iotivity-dev mailing list [email protected] https://lists.iotivity.org/mailman/listinfo/iotivity-dev
