On Aug 18, 2017 10:55 AM, "Dave Thaler via iotivity-dev" <
[email protected]> 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
[email protected]
https://lists.iotivity.org/mailman/listinfo/iotivity-dev
