I wouldn?t want to force people to NOT use doxygen markup comment blocks on private internal APIs. So instead what I proposed was ?anything published to out/ and NOT marked as experimental/preview/whatever? which requires we invent some way to mark something as experimental/preview.
Maybe OC_PREVIEW in some relevant position? it would be desirable to have a way to enable a compiler warning if code used any preview API, just like using a deprecated API. Suggestions for how to do that welcome. From: C.J. Collier [mailto:[email protected]] Sent: Tuesday, April 4, 2017 1:52 PM To: ???(Uze Choi) <uzchoi at samsung.com> Cc: Mats Wichmann <mats at wichmann.us>; Dave Thaler <dthaler at microsoft.com>; iotivity-dev at lists.iotivity.org Subject: Re: Re: [dev] Don't make breaking changes I propose that the selecting factor be whether the header file includes Doxygen markup comment blocks. On Mon, Apr 3, 2017 at 11:16 PM, ??? <uzchoi at samsung.com<mailto:uzchoi at samsung.com>> wrote: 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<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<https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Flists.iotivity.org%2Fmailman%2Flistinfo%2Fiotivity-dev&data=02%7C01%7Cdthaler%40microsoft.com%7Cca8420e5b9bf46d0d96c08d47b9c79db%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636269359362743654&sdata=0IZQJ1k1Bdei%2F87mlxm0zt9l0pgzSzcTzSWmHEhR3OA%3D&reserved=0> [cid:image001.gif at 01D2AD4C.0A722C20] [http://ext.samsung.net/mail/ext/v1/external/status/update?userid=uzchoi&do=bWFpbElEPTIwMTcwNDA0MDYxNjU2ZXBjbXMxcDRmYmM0NjE0NGQwNzZkYzk1MGExNWY1MmVjOWJmNmM4OCZyZWNpcGllbnRBZGRyZXNzPWNqY29sbGllckBsaW51eGZvdW5kYXRpb24ub3Jn] -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.iotivity.org/pipermail/iotivity-dev/attachments/20170404/dc301706/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/dc301706/attachment.gif>
