P4Runtime API versioning

[antoninbas]

@aghaffarkhah @wmohsin this is something we discussed offline but I cannot find any webpage describing this. Could you give an example of a protobuf file with version info?

[wmohsin]

I researched into how protobuf/gRPC based services are versioned. I found the following best-practice / recommendation: https://cloud.google.com/apis/design/versioning This is based on the industry-standard semantic versioning: https://semver.org/

This uses a MAJOR.MINOR.PATCH style version number scheme. The rules are to increment:

• 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.

Also, the major version number must be encoded as the last component of the proto package name. This would be p4.P4Runtime.v1 and p4.config.v1.

With a major version, the API must be evolved in a proto backwards-compatible manner described at https://cloud.google.com/apis/design/versioning#backwards_compatibility. See design compatibility for more details. I expect MAJOR version bump to be a rare event.

I propose that we adopt semantic versioning and the above guidelines for versioning P4Runtime.

I believe we are currently in initial development, but getting very close to 1.0.0 public API:

• link Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

Some services (e.g. gNMI) have chosen to use a custom proto option to represent a version of the service:

option (gnmi_service) = "0.6.0";

This is mostly for documentation/visibility. I would advise against this due to concerns noted in custom_options. Also, this has caused compatibility issues on targets that need to use custom non-x86 proto_lib.

The next step is to review this in a P4-API WG meeting.

[antoninbas]

Thanks for all the background information @wmohsin I think there is one small typo:

This would be p4.P4Runtime.v1 and p4.config.v1.

should probably be

This would be p4.v1 and p4.config.v1.

P4Runtime is the name of the service.

[chrispsommers]

I like this proposal. To determine the supported major versions, the controller can attempt a request using each major (semantic) version. Assuming we add a capability query request someday (https://github.com/p4lang/PI/issues/323) the controller can use this request to determine all the fine-grained capabilities, which could include major.minor.patch API version.

[antoninbas]

Decision at the 05/16/2018 P4 API WG meeting was to move forward with this proposal. As mentioned above, a client can check which major version is supported by attempting to connect to the appropriate service. It is probably a good idea to consider including a RPC in P4Runtime to query minor+patch version. I will open a PR which implements this proposal, so I'm re-assigning the issue to me.