View source for VPP/API Versioning

There is a newer document [[VPP/ApiChangeProcess]], making some parts of this document obsolete.

= API Versioning (draft) =

Evolving an API while maintaining some level of backwards compatibility is hard.

In the current implementation of the VPP API, each API message and each API module has a CRC value that an application can use to validate that an API has not changed unbeknownst to it. In this scheme every API change would be treated as backwards incompatible. This makes it difficult to both detect API changes, unless the application has stored away all the CRC values from a previous run, and it makes it difficult to write applications that will work against multiple versions of VPP.

This note only applies to applications using the binary VPP API. It is expected that plugins are always tied to and build with a specific version of VPP.

In other API specification languages, like proto3, there is support for adding new optional parameters to a given message, as long as this parameter is assigned a default. We might move to a similar notion in VPP, but this proposal currently limits itself to adding semantic versioning to API modules.

Each API module will have a semantic version statement of the form (see http://semver.org/)
vl_api_version <MAJOR>.<MINOR>.<PATCH>

* MAJOR version when you make incompatible API changes,
* MINOR version when you add functionality in a backwards-compatible manner, and
* PATCH version when you make backwards-compatible bug fixes.

In maintenance releases (e.g. from 17.10 to 17.10.1) only patches are allowed.

Prior to API freeze both backwards compatible and backwards incompatible changes are allowed. Backwards compatible changes must be thoroughly reviewed. Prior to each release there will be a run of the API-change verification tool, and one has to judge if doing a backwards incompatible change (like changing an existing message type), is better than adding a new message with a version tag, e.g. show_version_v3.  Please send an email to vpp-dev@lists.fd.io for all patches which contain api changes describing the reason for the change.

In the first release of a new API, since it is recognised that API's most often change initially, the MAJOR version should be set to 0, denoting EXPERIMENTAL.

If a new message type is added, the old message type must be maintained for at least one release. The change must be included in the release notes, and it would be helpful if the message could be tagged as deprecated in the API language and a logging message given to the user.

There is a new API message, api_versions that will return the list of API modules and their versions, so that an application can set which versions it depends on, and would fail early if it connects to a VPP version which has API module versions that are not supported.