all: investigate and document Proto v2 API usage

[tbpg]

http://google.golang.org/protobuf is the v2 version of http://github.com/golang/protobuf.

We should investigate how we can/should use it for cloud.google.com/go (among other Go repos).

We might also want to see if there is a way clients could use v2, even if our repos can't directly switch to v2.

We should also publish something in the root README saying what the plan is.

[tbpg]

cc @neild and @dsnet

[dsnet]

There should be relatively little public affect to using the newer API. Most of the protobuf usage is within the internal implementation, the only place places where the old API leaks to the exported API are in the following two packages:

• cloud.google.com/go/longrunning
• cloud.google.com/go/rpcreplay

where the older proto.Message interface is exposed in the public API. Fortunately, both packages are explicitly marked as "experimental and subject to change".

To upgrade to using the new API, I recommend doing the following:

• Upgrade to github.com/golang/protobuf@v1.4.0-rc.4 (this uses google.golang.org/protobuf@v1.20.0 under the hood).
• Run tests and make sure everything works.
• Regenerate all .pb.go files with protoc-gen-go@v1.4.0-rc.4.
• Run tests and make sure everything works. You may need to fix some brittle tests accidentally relying on unspecified behavior. See the release notes regarding generated code.
• Migrate the internal implementation to use the new API directly. By far, the most commonly used functions are proto.Equal and proto.Clone, both of which should be almost drop-in replaceable with the new API. The only difference is that the new API takes in the new Message interface. If you re-generate all .pb.go files, they will all be guaranteed to implement the new Message interface.

[johanbrandhorst]

What is the roadmap for this? Old generated versions of genproto is causing trouble for package maintainers who are trying to move to APIv2. Would be great with a timeline 😄.