Develop release policy

[dfawley]

gRPC-Go has several 1.x releases that depend upon this repo extensively for xds support. If a breaking change were to happen here, it would break gRPC-Go users.

If there are concerns about some parts of the repo being unstable, then we would be happy with a sub-module inside envoy that can be released as a stable v1 for the generated proto messages.

See also cncf/udpa#42. I believe this repo would also need a v1 release from the UDPA repo, since it is a dependency of several protos here.

cc @htuch, @markdroth

[dfawley]

@kyessenov - is this something you would be able to do? I also filed cncf/xds#2 to cover a dependency of this repo's (or cncf/udpa#42 if the protos are still coming from the deprecated UDPA repo).

[github-actions]

This issue has been automatically marked as stale because it has not had activity in the last 30 days. It will be closed in the next 7 days unless it is tagged "help wanted" or "no stalebot" or other activity occurs. Thank you for your contributions.

[dfawley]

Is there a 'never stale' label we can apply here?

also, cc @htuch

[mattklein123]

I don't think we currently have the resources to manage releases on this repo, but I will mark this help wanted for now.

[dfawley]

Proposal 1: the "quick and dirty" option if you don't mind releasing the go-control-plane server implementation as stable

1. Create a release with the tag v1.0.0

Proposal 2: version only the pb.go files maintained here and not the server

1. Add a go.mod file to envoy/

   cd envoy
   go mod init github.com/envoyproxy/go-control-plane/envoy
   sed -i 's/1\.1./1.11/' go.mod   # sed -i '' 's/1\.1./1.11/' go.mod on BSD/darwin/MacOS
   go mod edit -replace github.com/envoyproxy/go-control-plane=../
   go mod tidy
   

2. Commit the changes produced by the above to this repo.
3. Make a release of the new submodule (tag: envoy/v1.0.0)
4. Make a release of the base module without the envoy submodule (tag: v0.10.0)

Either of these options should require less than 20 minutes to perform, and would greatly help to improve the confidence of projects that wish to use xDS protos in Go (like gRPC-Go).

As mentioned in cncf/xds#2

Anyone writing a Go application that wishes to use Envoy protos will need a stable release of this repo. In case you are not aware, proto definitions cannot be generated independently by libraries, since multiple versions of the generated code for a single message that make their way into the same binary will cause a panic at init time.

I believe this is an important issue that should be addressed ASAP.

[dfawley]

Are there concerns about implementing one of the two proposals above? Managing releases doesn't need to be complex or time consuming.

[htuch]

@kyessenov @alecholmez @snowp thoughts?

[snowp]

I don't see a problem with it if ya'll are willing to do the work :)

I would think the second option of only versioning the protos would be the safest, I think that would also allow projects to import the protos without importing the whole control plane code? If so that might provide additional benefits as well

[alecholmez]

@htuch @mattklein123 I'd be more than happy to take this over and manage this! Would love to chat with you guys and potentially talk about future goals as well

[stevesloka]

I'm happy to help out as well!

[dfawley]

I would think the second option of only versioning the protos would be the safest, I think that would also allow projects to import the protos without importing the whole control plane code?

Because it's in the same repo, I believe the rest of the control plane code would be downloaded by any application using only the protos. But this would only be a minor cost, and external dependencies of packages not used by the application are not downloaded in either case.

[kyessenov]

I'm fine with the independently versioning the protos as well. It captures the right backwards compatibility expectations from Envoy APIs without tying the control plane to its existing interfaces. My main concern is the technical: how to achieve that with minimal pain. It was quite painful to have multi-module repos in the past, and I haven't revisited this subject in awhile.

[kyessenov]

On the second thought, Envoy APIs do have "alpha" packages that can have breaking changes. It would not be right to have "v1" with those packages. I think we'd need to pull out those extensions out of v1-versioned module if we are to follow this plan.

[dfawley]

It was quite painful to have multi-module repos in the past, and I haven't revisited this subject in awhile.

@kyessenov see my comment above for how to do multi-module repos here. We have several modules in https://github.com/grpc/grpc-go, and it's not difficult to manage.

On the second thought, Envoy APIs do have "alpha" packages that can have breaking changes

As long as they are very clearly indicated as such via the package name or comments visible via godoc, it should be safe to include alpha packages that are not subject to semver in a v1.x Go module.

[alecholmez]

I have no negatives on the multi-module repo versioning. I will say I think it's important we do version the logic external to the protos in this repo though. Quite a few large projects depend on the code in here (that are past v1.0) and IMHO it's important we don't break them (especially when landing things like incremental which make API changes).

Regarding the alpha protos, I agree with @dfawley, it's a users risk using an alpha versioned dependency. Alpha does not mean stable but I think it would be the job of THIS repo to make sure that is known as well as make sure we version in a way that is inclusive to the fast moving nature of the proto stubs. +1 for me on the multi-module versioning but I think we need to call this repo a v1 at the very least. Whether we wait for incremental to go in or do it now I'm indifferent on.

[alecholmez]

Hi all, I made this document:

Proposal: Multi-Module Release Plan

@dfawley Feel free to edit as you please or add yourself as a doc owner. This was your proposal after all. I think it might be worth outlining what importing this project would look like if we're going down the multi-module route

[dfawley]

The doc LGTM, but you may also want to explicitly capture steps 2-4 in my comment, which are also important.

The process for importing packages in this repo wouldn't change for users. Users would probably want to do a go get github.com/envoyproxy/go-control-plane/envoy@v1.0 && go mod tidy (optional) after the release is performed, just to see "v1" instead of "v0" in their go.mod files.

[dfawley]

Is there a path forward here? How can we make this happen?

[derekperkins]

It seems like there is consensus on using multiple modules. Is there anything else to discuss before this gets implemented?

[jpeach]

xref #492
xref #467

[sunjayBhatia]

would there be any appetite in the sub-module tag being cut/based on Envoy release version? e.g. when envoy X.Y releases, the automation to mirror the API changes would also tag envoy/X.Y

thinking about the case(s) where new fields are added to the protos but you may be relying on an older Envoy version etc.

[alecholmez]

@sunjayBhatia I think that might actually be a good idea. If we can automate that whenever they cut their release it triggers a sub module release on this end that would be very cool. This was originally high on my priority list but I let it fall off. I'd say let's revisit

[jpeach]

thinking about the case(s) where new fields are added to the protos but you may be relying on an older Envoy version etc.

There are cases where you need both the old and new protobuf definition to bridge an API change. The first part of this problem is having both of the generated definitions (I think the submodule version proposal works for this). The second part is swizzling the types in the protobuf registry so you don't have 2 types trying to claim the same name. Not sure how to deal with that part.

[jpeach]

@sunjayBhatia making the Go modules change now would only be useful for Envoy 1.21 and later, right?

[sunjayBhatia]

@sunjayBhatia making the Go modules change now would only be useful for Envoy 1.21 and later, right?

yeah if tying it to Envoy releases works/we do that, it would only be useful going forward

[jpeach]

@sunjayBhatia making the Go modules change now would only be useful for Envoy 1.21 and later, right?

yeah if tying it to Envoy releases works/we do that, it would only be useful going forward

Actually, it might be possible to tag the submodule with older versions of the envoy protobufs. Would need to do some branching and tedious manual hackery, but could be doable?

[alecholmez]

Honestly it might not be worth the hassle. If users need compatibility with an older version they can just pin (similar to what we did with the v2 removal). IMO i think it's easiest to just tag the submodule, list compatibility as 1.21 and document if you'd like an older version of envoy please use previous releases of go-control-plane.

[jpeach]

See also discussions in envoyproxy/envoy#28041 and #723.