Difference between revisions of "VPP/ApiChangeProcess"

From fd.io
< VPP
Jump to: navigation, search
(Use cases)
(Replaced content with "__NOTOC__ The VPP API Change process has been moved into the VPP git repository in the [https://github.com/FDio/vpp/blob/master/src/tools/vppapigen/VPPAPI.rst#api-change-...")
 
(12 intermediate revisions by one other user not shown)
Line 1: Line 1:
WORK IN PROGRESS
+
__NOTOC__
  
= Purpose =
+
The VPP API Change process has been moved into the VPP git repository in the [https://github.com/FDio/vpp/blob/master/src/tools/vppapigen/VPPAPI.rst#api-change-process VPP API Language document].
 
+
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.
+
 
+
== An in-progress API accidentally marked as "production" ==
+
 
+
This is expected to mainly apply during the initial period of 20.05->20.09, the proposal is to have it active for 4 weeks from Jun 17 till July 15th, with the following process.
+
 
+
If a developer finds that a given API or a set of APIs is not ready for production due to lack of tests and/or the general API stability, then they:
+
1) Create a new gerrit change with *just* the marking of the API as in_progress, subject being: "API downgrade: ... which APIs and why are downgraded..."
+
2) Add ayourtch@gmail.com as a reviewer (for help guiding the process)
+
3) Send an email to vpp-dev mailing list with the subject being the same as the oneliner commit message, reference to the gerrit change, and the reasoning.
+
4) Wait for the timeout period of two weeks for the feedback
+
5) If no feedback received, assume the community agreement and commit the change to master branch.
+
 
+
This needs to be highlighted that this (or whatever is agreed upon) process is an *exception* - normally the transition is always in_progress => production => deprecated.
+
 
+
== 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.
+
 
+
= Details =
+
 
+
 
+
See https://gerrit.fd.io/r/c/vpp/+/26881
+

Latest revision as of 16:01, 18 July 2023


The VPP API Change process has been moved into the VPP git repository in the VPP API Language document.