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
* All public APIs must be in a header file that is published to the build
directory
* All public APIs must be fully documented using doxygen markup in the
public header files
* 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.
* Public APIs cannot have source- or binary- breaking changes across
IoTivity versions
(Breaking changes can be made to a new API only until it is released
for the first time.)
1.2 Experimental APIs
---------------------
Experimental APIs are considered to be potential future public APIs, but there
is no guarantee
of support in future releases, nor is there any guarantee that breaking changes
will not occur
across releases.
Experimental API requirements:
* Experimental APIs must be optional to compile in. That is, there must be
some way to
build IoTivity in a way that does not expose any experimental APIs, so
that an application
can easily verify that it uses only fully-supported public APIs, and so
that the IoTivity
code size requirement can be minimized.
* Experimental APIs must be in a header file that is published to the build
directory.
They can be in their own header, or in a header file that is shared with
public APIs but
only if surrounded by an appropriate ifdef.
* Experimental APIs should be fully documented using doxygen markup in the
header file
* Experimental APIs should ideally 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.
Having working samples may help others evaluate and determine how ready
it is for prime time
before the API moves from experimental to public.
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.
Internal API requirements:
* Internal APIs must not appear in any header file that is published to the
build directory
* Internal APIs should ideally be documented using doxygen markup in the
private header files
* Internal APIs must not be used in sample code
* 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.
2 Programming Languages
-----------------------
There may be multiple programming languages supported (whether publically or
experimentally).
The API maintainer may have a separate sub-maintainer per programming language.
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.
* 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.
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.
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.
Please send feedback to the list.
Thanks,
Dave Thaler (as API function maintainer)
_______________________________________________
iotivity-dev mailing list
[email protected]
https://lists.iotivity.org/mailman/listinfo/iotivity-dev
