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> 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> > *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> > > 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. > > 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 listiotivity-dev at > lists.iotivity.orghttps://lists.iotivity.org/mailman/listinfo/iotivity-dev > > > > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.iotivity.org/pipermail/iotivity-dev/attachments/20170404/c37b10ea/attachment.html> -------------- next part -------------- A non-text attachment was scrubbed... Name: not available Type: image/gif Size: 13402 bytes Desc: not available URL: <http://lists.iotivity.org/pipermail/iotivity-dev/attachments/20170404/c37b10ea/attachment.gif>
