Tl;DR:
cabe.v1
, cabe.v2
, etc...CABE uses semantic versioning, however only the major version (v1
, as of this writing) is exposed in cabe's proto package name.
Minor version changes and patch version changes (i.e. non-breaking changes) do not require changes to CABE's proto package name, but any breaking changes do require a major version change, which means updating the proto package name from cabe.v<n>
to cabe.v<n+1>
, and potentially creating new ./v[n+1]/
paths under this directory to contain the updated .proto
files.
CABE does not use API stability channels for versioning, as it does not have enough distinct users to justify the additional overhead to implement and maintain them.
AIP 215 offers some guidance on this topic, which CABE should follow. In particular:
All protos specific to an API must be within a package with a major version
Since CABE is implemented in Go, once the API reaches v2
, the generated Go code for its protos should include the major version in their Go package name as well. While the current v1
protos can declare:
option go_package = "go.skia.org/infra/cabe/go/proto";
However, the next major version should instead use:
option go_package = "go.skia.org/infra/cabe/go/proto/v2";
and so on.
For any go module, versions v0
and v1
, it is not necessary to indlude the major version in the Go package name. See the official Go module documentation for more details about why this is the case.
Use the standard protobuf style guide.
The CABE gRPC service hosted at cabe.skia.org already had users at the time of its launch and was a ported from an internally hosted service with the same proto interface. Therefore v1
is the first major version for the gRPC API, rather than v0
.
The proto message and grpc service definitions for v1
are located in the ./v1 subdirectory, and any major API version changes should be defined by files in sibling ./v{2...N}
subdirectories.