> All good except that DEPRICATED is misspelled… should be OC_DEPRECATED (no 
> I).   What you show is what was done in the AllJoyn code base if I remember 
> correctly, and I’m fine with doing the same in the iotivity code base.

Good thing I spelled it correctly in the actual commit. (Common typo for me 
unfortunately.) I referenced the AllJoyn code base to make this change. The 
main reason I like this change is it puts the change right in the face of any 
developer using the code. If the compiler supports printing compiler warnings  
they will see warnings.  There is no need to reference documentation because 
the tools they already use will tell them the code is deprecated. This gives us 
a much higher confidence that developers know they are using deprecated code.

George

From: Dave Thaler [mailto:dtha...@microsoft.com]
Sent: Wednesday, January 3, 2018 2:43 PM
To: Nash, George <george.n...@intel.com>; Gregg Reynolds <d...@mobileink.com>
Cc: iotivity-dev <iotivity-dev@lists.iotivity.org>
Subject: RE: [dev] Proposed API guidelines

Gregg wrote:
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.   Historically, iotivity culture has been to throw in all kinds 
of extra features and APIs (e.g., cloud support).   If you’d like to argue that 
such features should not be in the master branch until they are production 
quality (including using only APIs that only meet the public API requirements), 
that’s a fine discussion for the list here, and not specific to APIs so wider 
than just what I as API maintainer would cover.

More below…

From: Nash, George [mailto:george.n...@intel.com]
Sent: Wednesday, January 3, 2018 1:37 PM
To: Gregg Reynolds <d...@mobileink.com<mailto:d...@mobileink.com>>; Dave Thaler 
<dtha...@microsoft.com<mailto:dtha...@microsoft.com>>
Cc: iotivity-dev 
<iotivity-dev@lists.iotivity.org<mailto:iotivity-dev@lists.iotivity.org>>
Subject: RE: [dev] Proposed API guidelines

> The whole concept of "experimental API" makes little sense to me. "Release 
> with experimental (i.e. non-production) APIs" strikes me as an oxymoron.

> 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?
> 1.3 Internal APIs
The theory behind experimental API is not a hard to understand as you may 
think.  It is code that has been developed and is intended to be 
production-quality.  Maybe the branch did not attract much attention or could 
benefit from more eyes looking at the code. Till it is merge with master it 
will not get the attention of the community. It is a way to introduce code that 
is believed to be ready for release but due to circumstances the developers 
want to leave it open to API breaking changes if something is discovered that 
was missed. A way to think of it would be a public beta for the code in 
question.

Some OSS projects have separate STABLE vs BETA releases for this distinction.   
Using George’s definition above, all iotivity releases would be BETA releases 
and none are STABLE releases.   Splitting APIs into public vs experimental 
means the same release can have both STABLE and BETA APIs in the same release, 
to distinguish them.   That helps with that issue, but does not help with the 
issue of underlying features that might be BETA quality features that might 
affect STABLE features.

> APIs can be deprecated by marking them as @deprecated.  The associated text 
> should explain
> what an application should do instead.  Public APIs must be @deprecated for 
> at least two
> releases before they can be removed.  The reasons for deprecation of APIs 
> should be discussed
> on the iotivity-dev list.

Along with the @depricated doxygen tag, I have been trying to introduce an 
OC_DEPRECATED macro that can be used in C and C++ code to add compiler specific 
keywords so the compiler will tell the user of the code they are using 
deprecated functions/classes via compiler warnings.

https://gerrit.iotivity.org/gerrit/#/c/23111/<https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgerrit.iotivity.org%2Fgerrit%2F%23%2Fc%2F23111%2F&data=02%7C01%7Cdthaler%40microsoft.com%7Caea19bc778ec4c10a44208d552f20f5d%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C1%7C636506121968890185&sdata=QEZNcuzsrSYPEKplaRMUJVZUh%2B%2Be6lzkil9AIImQiHY%3D&reserved=0>


example:
I want to deprecate function `void foo()`

I would write the following:

/**
  @depricated foo has been deprecated due to security problems. Please use 
bar(). See IOT-1234 for more information
/*
OC_DEPRICATED(
void foo(),
2018.01);

Or

/**
  @depricated foo has been deprecated due to security problems. Please use 
bar(). See IOT-1234 for more information
/*
OC_DEPRICATED_MSG(
void foo(),
“foo has been deprecated due to security problems. Please use bar(). See 
IOT-1234 for more information”,
2018.01);

All good except that DEPRICATED is misspelled… should be OC_DEPRECATED (no I).  
 What you show is what was done in the AllJoyn code base if I remember 
correctly, and I’m fine with doing the same in the iotivity code base.


From: 
iotivity-dev-boun...@lists.iotivity.org<mailto:iotivity-dev-boun...@lists.iotivity.org>
 [mailto:iotivity-dev-boun...@lists.iotivity.org] On Behalf Of Gregg Reynolds
Sent: Tuesday, January 2, 2018 9:46 PM
To: Dave Thaler <dtha...@microsoft.com<mailto:dtha...@microsoft.com>>
Cc: iotivity-dev 
<iotivity-dev@lists.iotivity.org<mailto:iotivity-dev@lists.iotivity.org>>
Subject: Re: [dev] Proposed API guidelines



On Aug 18, 2017 10:55 AM, "Dave Thaler via iotivity-dev" 
<iotivity-dev@lists.iotivity.org<mailto:iotivity-dev@lists.iotivity.org>> 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"
    * 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?
        (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.
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.

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?
1.3 Internal APIs
-----------------
Internal APIs are considered to be usable within IoTivity but are not intended 
to be used
by applications that use IoTivity.
Check.
Internal API requirements:
    * Internal APIs must not appear in any header file that is published to the 
build directory
See above. I guess you mean publicly exposed include directory?
    * Internal APIs should ideally be documented using doxygen markup in the 
private header files
Check
    * Internal APIs must not be used in sample code
Check
    * Internal APIs must not be used by any apps other than test code.  For 
example, this means
       that sample provisioning apps must not use internal APIs.
"not be used by any official sample apps..'

2 Programming Languages
Suggest: "Language Bindings"
-----------------------
There may be multiple programming languages supported (whether publically or 
experimentally).
The API maintainer may have a separate sub-maintainer per programming language.
I'm not sure you want to get into that unless you want to define an abstract 
Iotivity API  (like DOM). After all anybody can implement a language binding in 
any way they see fit. The project could adopt a few "official" bindings (Java, 
JavaScript) but that's a lot of work, and you also do not want to discourage 
innovation.

3 Breaking Changes
------------------
The API maintainer shall be responsible for API breaking change policy.  The 
proposed policy is:
    * Public APIs cannot have source- or binary- breaking changes across 
releases, except as
      covered by deprecation as explained below.  API additions can be made at 
any time.
See above note regarding binary compatibility.
    * Experimental and internal APIs can have breaking changes across releases.

APIs can be deprecated by marking them as @deprecated.  The associated text 
should explain
what an application should do instead.  Public APIs must be @deprecated for at 
least two
releases before they can be removed.  The reasons for deprecation of APIs 
should be discussed
on the iotivity-dev list.
Check

4 Gerrit review
---------------
All changes that affect any public API header must include the API maintainer 
and/or appropriate
language-specific sub-maintainers as code reviewers.  The (sub)maintainers are 
responsible for
ensuring that the above guidelines are met, and also reviewing the doxygen 
documentation for
completeness and clarity.
Check
Implementers are encouraged to discuss the proposed APIs on the iotivity-dev 
list before they
are implemented, since changes are typically much more costly after the APIs 
are implemented.
Check
Please send feedback to the list.
Check. ;)

Gregg
_______________________________________________
iotivity-dev mailing list
iotivity-dev@lists.iotivity.org
https://lists.iotivity.org/mailman/listinfo/iotivity-dev

Reply via email to