Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Develop release policy #391

Open
dfawley opened this issue Feb 4, 2021 · 28 comments · May be fixed by #714
Open

Develop release policy #391

dfawley opened this issue Feb 4, 2021 · 28 comments · May be fixed by #714

Comments

@dfawley
Copy link
Member

dfawley commented Feb 4, 2021

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
Copy link
Member Author

dfawley commented Mar 3, 2021

@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
Copy link

github-actions bot commented Apr 6, 2021

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.

@github-actions github-actions bot added the stale label Apr 6, 2021
@dfawley
Copy link
Member Author

dfawley commented Apr 6, 2021

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

also, cc @htuch

@github-actions github-actions bot removed the stale label Apr 6, 2021
@mattklein123
Copy link
Member

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

@mattklein123 mattklein123 changed the title Need a stable v1.0 release Develop release policy Apr 6, 2021
@dfawley
Copy link
Member Author

dfawley commented Apr 6, 2021

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
Copy link
Member Author

dfawley commented May 12, 2021

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

@htuch
Copy link
Member

htuch commented May 12, 2021

@kyessenov @alecholmez @snowp thoughts?

@snowp
Copy link
Contributor

snowp commented May 12, 2021

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
Copy link
Contributor

@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
Copy link
Member

I'm happy to help out as well!

@dfawley
Copy link
Member Author

dfawley commented May 13, 2021

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
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Member Author

dfawley commented May 20, 2021

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
Copy link
Contributor

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
Copy link
Contributor

alecholmez commented May 28, 2021

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
Copy link
Member Author

dfawley commented Jun 2, 2021

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
Copy link
Member Author

dfawley commented Jun 18, 2021

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

@derekperkins
Copy link

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

@jpeach
Copy link
Contributor

jpeach commented Oct 12, 2021

xref #492
xref #467

@sunjayBhatia
Copy link
Member

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
Copy link
Contributor

alecholmez commented Jan 5, 2022

@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
Copy link
Contributor

jpeach commented Jan 6, 2022

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
Copy link
Contributor

jpeach commented Jan 6, 2022

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

@sunjayBhatia
Copy link
Member

@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
Copy link
Contributor

jpeach commented Jan 6, 2022

@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
Copy link
Contributor

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
Copy link
Contributor

jpeach commented Jun 30, 2023

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

10 participants