Motivation

We discussed @ FU Berlin a while back offline that it might be a good idea to version some of our user facing APIs to make communication of changes in the API more obvious beyond just the RIOT release. And since I smell some major API reworks coming again (#8351, a sock rework @kaspar030 was proposing in #8149, ...) I think it is about time to pick this discussion up again.

What are user facing APIs

Well... that needs to be discussed... I think that versioning all header files would be overkill. When they are identified they should be collected on a special page in the documentation for any user easy to find (which we should do anyway for new users, regardless of versioning) including their current version. From the top of my head I would include definitively and in no particular order:

• most if not all files in core/include/
• netdev
• saul
• xtimer
• event
• sock
• vfs
• ...

How to version

Notation

In doxygen there is the @version tag which I think we can use. For example sock would be versioned in sys/include/net/sock.h

/**
 * @defgroup    net_sock    Sock API
 * @ingroup     net
 * @brief       Provides a network API for applications and library
 * @version     v1.1.0      Asynchronous event management added
 * @version     v1.0.0      Initial sock version
 * @version     v0.1.0      Initial conn version
 * ...

Maybe even add the commit hash that changed the API to it as well.

Scheme

As to what scheme to use for versioning, semantic versioning was tossed around by @cladmi, @kYc0o and @aabadie: The version is a triple consisting of 3 numbers

1. Major version: increments (and resets 2 and 3 to 0) whenever an API change makes it incompatible with software that uses an older version of the API.
2. Minor version: increment (and resets 3) whenever an API change adds functionality in a backwards-compatible manner.
3. Patch version: increments whenever there is a backwards-compatible bug-fix to the API (e.g. making a pointer in a function parameter const, moving from a specific pointer to a generic void * pointer etc.).

API deprecation

With this process we could also add a BCP for API deprecation:

• Add @deprecated tag over @version tags with a warning that this API will be removed after x releases (let's say 2, unless not all depending mainline features were ported until then).
• After x releases remove deprecated API
• Add the API with removal commit to lost&found