One issue is if someone changes a public non-experimental API and changes all the callers in the iotivity project (e.g., all samples) then the break goes undetected. Another issue is if there is a public non-experimental API without any unit tests or sample, then the break again goes undetected.
Another issue is that there?s no convention in use to tag experimental (aka preview) APIs. We have @deprecated but nothing like @experimental or @preview. We should probably define some actual compile-time annotation (not just doxygen) to indicate ?preview? (experimental) APIs that may change in the next release. That?s what we do with Microsoft APIs and it works well. Anything without such an annotation could be relied on to not change other than being @deprecated. From: C.J. Collier [mailto:[email protected]] Sent: Monday, April 3, 2017 6:19 PM To: Dave Thaler <dthaler at microsoft.com> Cc: iotivity-dev at lists.iotivity.org Subject: Re: [dev] Don't make breaking changes Yes. Let's codify this with JJB defintions, compliance verification tests that feed back to gerrit. Do not allow code in to the repository which breaks the build. Run the build successfully before completing a merge. We can ensure that these things do not happen with the tools at our disposal. Gerrit has some plugins that will allow group-based ACLs using the same LDAP back-end we use for identity.linuxfoundation.org<http://identity.linuxfoundation.org>. The legacy internal ms tools developed for use with source depot, perforce and active directory could also likely be changed slightly to make use of the CI infrastructure we have in place. In the meantime, I urge you to take a look at the codebase we have of job definitions here: https://gerrit.iotivity.org/gerrit/gitweb?p=ci-management.git;a=blob;f=jjb/iotivity/iotivity-jobs.yaml;hb=HEAD If the job as presently defined is allowing bad builds through, I think we should be more conservative about when we fail the build and that we should do it early and immediately so that we can find the problems easily in the logs. Thoughts? C.J. On Mon, Apr 3, 2017 at 2:01 PM, Dave Thaler via iotivity-dev <iotivity-dev at lists.iotivity.org<mailto:iotivity-dev at lists.iotivity.org>> wrote: I would like to remind all contributors of the guidance on https://wiki.iotivity.org/platform_support which was posted to the list last year and has been on the wiki ever since. Specifically this part: A core feature is supported on all fully-supported platforms, where (at the time of an IoTivity release) it: ? ? Can have API additions but not breaking changes across releases This is about public API surface area, which are APIs in .h files that are not under an ?/internal? subtree. Such .h files should be copied to the out/ directory by the build, and it is not appropriate to change API prototypes, or to mess with existing structs, in a way that makes changes since the last major release that would affect apps. So for example, if a shared library is built by the iotivity build, then any app that links with it should continue to work. Similarly, any app that (say) declares a struct on the stack in its own code, should similarly continue to work (changes in struct size and field offsets are breaking changes). I?ve been seeing changes to prototypes and structs that could cause problems with existing apps even if they and iotivity are both recompiled. Given the lack of objection last year, I wanted to remind people since people seem to be ignoring it. The alternative is to say that IoTivity 1.3 is not backwards compatible for apps and people should not be writing any apps yet. Since there?s no API maintainer, I?m bringing this up as platform support maintainer since the platform support guidelines have included API support guidelines. If folks have issues, please discuss. Dave _______________________________________________ iotivity-dev mailing list iotivity-dev at lists.iotivity.org<mailto:iotivity-dev at lists.iotivity.org> https://lists.iotivity.org/mailman/listinfo/iotivity-dev -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.iotivity.org/pipermail/iotivity-dev/attachments/20170404/70cf2f73/attachment.html>
