VPP/ApiChangeProcess
WORK IN PROGRESS
Contents
Purpose
To minimize the disruptions to the consumers of the VPP API, while permitting the innovation for the VPP itself.
Motivation
Historically, API changes in VPP master branch were allowed at any point in time outside of a small window between the API freeze milestone and RC1 milestone. The API changes on the throttle branches were not permitted at all.
This model proved workable, however all the production use cases end up on throttle branches, with a lot of forklift activity when it is the time to upgrade to the next branch. The LTS releases were the first one to de-facto introduce the idea "It is okay to add a new API call, if no other APIs change at all".
This document outlines the structured process that harmonizes the behavior across all the VPP branches, and allows more flexibility for the consumer, while permitting the innovation in the VPP itself.
The Core Promise
"If a user is running a VPP version N and does not use any deprecated APIs, they should be able to simply upgrade the VPP to version N+1 and there should be no API breakage".
In-Progress, Production and Deprecated APIs
This proposal adds a classification of stability of an API call:
- "In-Progress": APIs in the process of the development, experimentation, and limited testing. - "Production": tested as part of the "make test", considered stable for general usage. - "Deprecated": used as a flag on Production APIs which are slated to be deprecated in the future release.
The "In-Progress" APIs or the APIs with the semantic version of 0.x.y are not subject to any stability checks, thus the developers are free to introduce them, modify their signatures, and as well remove them completely at will. The users should not use the in-progress APIs without the interactions with its maintainers, nor base the production code on those APIs. The goal of "in-progress" APIs to allow rapid iteration and modifications to ensure the API signature and function is stabilized. These API calls may be used for testing or experimentation and prototyping.
When the maintainer is satisfied with the quality of the APIs, and ensures that they are tested as part of the "Make test" runs, they can transition their status to "Production".
The "Production" APIs can *NOT* be changed in any way that modifies their representation on the wire and the signature (thus CRC). The only change that they may incur is to be marked as "Deprecated". These are the APIs that the downstream users can use for production purposes. They exist to fulfil a core promise of this process: The "Deprecated" APIs are the "Production" APIs that are about to be deleted. To ensure the above core promise is maintained, if the API call was marked as deprecated at any point between RC1 of release N and RC1 of release N+1, it MUST NOT be deleted until the RC1 milestone of the release N+2. The deprecated API MAY specify a replacement API - which MUST be a Production API, so as not to decrease the level of stability.
Use cases
Adding a new field to a production API
The simplest way to add a new field to a Porduction API message *foo_message* is to create a new In-Progress message *foo_message_v2*, and add the field to that one. Typically it will be an extension - so the API message handlers are trivially chained. If there are changes/adjustments that are needed, this new message can be freely altered without bothering the users of the Production API.
When the maintainer is happy with the quality of the implementation, and the foo_message_v2 is tested in "make test" to the same extent as the foo_message, they can make two commits: one, removing the in-progress status for foo_message_v2, and the second one - deprecating foo_message and pointing the foo_message_v2 as the replacement. Technically after the next throttle pull, they can delete the foo_message - the deprecation and the replacement will be already in the corresponding branch.
Rapid experimentation for a new feature
Add a message that is in-progress, and keep iterating with this message. This message is not subject to the change control process.
Real-world examples
https://gerrit.fd.io/r/c/vpp/+/25810 - rather than building an incompatible field change, a different, new in-progress API was made for rapid innovation.