My thoughts inline: From: Dave Thaler Sent: Tuesday, April 4, 2017 10:15 AM To: Daniel Mihai <Daniel.Mihai at microsoft.com>; Wouter van der Beek (wovander) <wovander at cisco.com>; uzchoi at samsung.com; Mats Wichmann <mats at wichmann.us>; C.J. Collier <cjcollier at linuxfoundation.org> Cc: iotivity-dev at lists.iotivity.org Subject: RE: [dev] Don't make breaking changes
The rule as I understand it is supposed to be that if a .h file is not in an /internal subdirectory it?s public and should be copied to /out by the build. Anything that doesn?t follow that rule should have a bug filed. [DM] /out is currently broken. We already have sample apps that include internal/ headers. Hypothetically, third-party apps could have the same problem. I agree that we should file bugs *and fix* these problems. As I said, I expect that will take significant time. Please feel free to prove me wrong though. It?s important to keep API compat once you have real apps. Not having stable APIs is fine as long as you have no real world deployment. [DM] I agree. But, it?s even worse to be locked down into a set of bad APIs. Also, does IoTivity have significant real world deployment at this point? I don?t think that?s the state we want to be in. It?s fine to deprecate APIs and add new ones, if API surface area needs to change. But not declaring anything stable is a good way to kill any app usage, and iotivity needs apps. From: Daniel Mihai Sent: Tuesday, April 4, 2017 9:53 AM To: Wouter van der Beek (wovander) <wovander at cisco.com<mailto:wovander at cisco.com>>; uzchoi at samsung.com<mailto:uzchoi at samsung.com>; Mats Wichmann <mats at wichmann.us<mailto:mats at wichmann.us>>; Dave Thaler <dthaler at microsoft.com<mailto:dthaler at microsoft.com>>; C.J. Collier <cjcollier at linuxfoundation.org<mailto:cjcollier at linuxfoundation.org>> Cc: iotivity-dev at lists.iotivity.org<mailto:iotivity-dev at lists.iotivity.org> Subject: RE: [dev] Don't make breaking changes I agree with the goal of getting to a stable set of Public IoTivity APIs, and to avoid breaking changes to those Public APIs. I don?t think we are anywhere close to that goal though. Some of the reasons: 1. As others have said below: there are too many sets of APIs and there is no ?official? list of Public APIs yet. 2. Different OS?s/platforms seem to have different requirements. For example: a. If I understand correctly, non-static C functions in a Linux shared library can be called by anyone outside the shared library. b. On Windows, we need to identify those functions that can be called by anyone outside the shared library, and explicitly add them to the exports list, one by one. Does this mean that all of the functions from (a) and (b) are Public and cannot get breaking changes? That?s typically the approach on Windows, but it is not clear to me if is the proper approach on Linux too. For example, on Linux, it appears that: A. Shared library ocpmapi calls CredToCBORPayload B. Shared library octbstack contains the CredToCBORPayload implementation Does that mean CredToCBORPayload should be treated as a Public API, that cannot incur breaking changes? It doesn?t seem that the authors of CredToCBORPayload meant it to be Public. I think it?s too early to lock down the IoTivity APIs. We need a lot more clean-up and untangling before we?ll be able to achieve that lockdown. Dan From: iotivity-dev-bounces at lists.iotivity.org<mailto:iotivity-dev-bounces at lists.iotivity.org> [mailto:[email protected]] On Behalf Of Wouter van der Beek (wovander) Sent: Tuesday, April 4, 2017 1:57 AM To: uzchoi at samsung.com<mailto:uzchoi at samsung.com>; Mats Wichmann <mats at wichmann.us<mailto:mats at wichmann.us>>; Dave Thaler <dthaler at microsoft.com<mailto:dthaler at microsoft.com>>; C.J. Collier <cjcollier at linuxfoundation.org<mailto:cjcollier at linuxfoundation.org>> Cc: iotivity-dev at lists.iotivity.org<mailto:iotivity-dev at lists.iotivity.org> Subject: Re: [dev] Don't make breaking changes + 1 for having an experimental indication on the APIs, e.g. not yet part of OCF standards, but work in progress to get there. I think we also should have an indication that an feature is unrelated to OCF. About APIs: all of the APIs should not break between versions. But can we please start with the Iotivity Base (C SDK)? https://wiki.iotivity.org/initialize_setting since that is the base of everything. Note that I only can see which other APIs should exist at https://wiki.iotivity.org/start The Programming Guide This is is a nice overview of what is there, but it should have links to the APIs mentioned below in the email. Note: I also think that this section is wrongly placed in the Wiki, all other sections in this page are about the development and processes in IOTIvity, this section is about using IOTivity to make products. Kind Regards, Wouter From: iotivity-dev-bounces at lists.iotivity.org<mailto:iotivity-dev-bounces at lists.iotivity.org> [mailto:[email protected]] On Behalf Of ??? Sent: 04 April 2017 07:17 To: Mats Wichmann <mats at wichmann.us<mailto:mats at wichmann.us>>; Dave Thaler <dthaler at microsoft.com<mailto:dthaler at microsoft.com>>; C.J. Collier <cjcollier at linuxfoundation.org<mailto:cjcollier at linuxfoundation.org>> Cc: iotivity-dev at lists.iotivity.org<mailto:iotivity-dev at lists.iotivity.org> Subject: Re: [dev] Don't make breaking changes We need to select which API sets are to be managed well. Among csdk, C++ resource, IPCA, Resource Encapsulation, Smart home class, some service component API set, constrained fw API, what should we keep well? Any idea to make it? BR Uze Choi --------- Original Message --------- Sender : Mats Wichmann <mats at wichmann.us<mailto:mats at wichmann.us>> Date : 2017-04-04 11:07 (GMT+9) Title : Re: [dev] Don't make breaking changes On 04/03/2017 07:25 PM, Dave Thaler via iotivity-dev wrote: > 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:cjcollier at linuxfoundation.org] > Sent: Monday, April 3, 2017 6:19 PM > To: Dave Thaler <dthaler at microsoft.com<mailto:dthaler at microsoft.com>> > Cc: iotivity-dev at lists.iotivity.org<mailto: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. There are several things... We do have a system which requires a patch build (and pass the unit tests) when applied in order to get a +1 from jenkins. I'm not completely sure if you have to ask for that (jenkins as reviewer), it has seemed to me it's not. That's fine - there have been a few "build is broken now" episodes which indicates occasional lack of discipline as to when the changes are actually pushed, but those have been essentially minor hiccups, soon fixed. Dave was talking about detecting changes to the the API, which is not the same as a build fail. You could conceive of having API-validation tests be part of automated acceptance checks also, but I don't think we have that now. I've only looked at a small number of the unit tests; those are useful but they don't seem to be constructed as a complete validation of the API details. "Compliance tests" (if we mean running the CTT?) would help here, but I don't think anyone believes at an IoTivity API level those are thorough enough yet. As an outsider, I haven't heard much about the progress of the validation development contract, or whether that could be applied at such a fine-grained level (a gerrit hook that could detect an API-breaking change). And then I'm not convinced we have a precise enough definition of what "the API" (one or several) actually is. I think this falls partly in the area of Dave's observation that we don't have an API Maintainer, but perhaps even more than that - it's hard to put that all on a person, you want to have things completely clear in markup and tooling. Again I'm just pretty much repeating Dave here... so I'll stop restating and leave it for others to comment. _______________________________________________ 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 [cid:image001.gif at 01D2AD2F.5E03EF30] [http://ext.samsung.net/mail/ext/v1/external/status/update?userid=uzchoi&do=bWFpbElEPTIwMTcwNDA0MDYxNjU2ZXBjbXMxcDRmYmM0NjE0NGQwNzZkYzk1MGExNWY1MmVjOWJmNmM4OCZyZWNpcGllbnRBZGRyZXNzPWlvdGl2aXR5LWRldkBsaXN0cy5pb3Rpdml0eS5vcmc_] -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.iotivity.org/pipermail/iotivity-dev/attachments/20170404/f3d246e8/attachment.html> -------------- next part -------------- A non-text attachment was scrubbed... Name: image001.gif Type: image/gif Size: 13402 bytes Desc: image001.gif URL: <http://lists.iotivity.org/pipermail/iotivity-dev/attachments/20170404/f3d246e8/attachment.gif>
