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

Prepare for plugin protocol versioning #19392

Closed
apparentlymart opened this issue Nov 17, 2018 · 1 comment · Fixed by #19393
Closed

Prepare for plugin protocol versioning #19392

apparentlymart opened this issue Nov 17, 2018 · 1 comment · Fixed by #19393
Milestone

Comments

@apparentlymart
Copy link
Contributor

apparentlymart commented Nov 17, 2018

Right now we have our single protobuf protocol definition living in plugin/proto. Our design for protocol versioning moving forward requires that the protocol definitions and their associated Go packages to include the version number so we're explicit about it in case of introducing a new protocol version 6 alongside 5 in a later release.

Therefore:

  • The plugin/proto package should move to internal/tfplugin5.
  • Its plugin.proto should be tfplugin5.proto
  • The package declaration in tfplugin5.proto should be package tfplugin5;
  • The generated Go package should also declare itself as package tfplugin5
  • All existing importers of plugin/proto should import instead as import proto "github.com/hashicorp/terraform/internal/tfplugin5"
  • The make proto Makefile target will need to run the generator in the new directory instead.
  • internal/tfplugin5/tfplugin5.proto should have a comment at the top announcing it as the definition of protocol version 5.0. Future minor releases of the protocol will update this file in-place, announcing as version 5.1 etc over time.
  • External implementers of our protocol (i.e. future SDKs in other languages) should copy the tfplugin5.proto file at the version they intend to implement into their own repository and use protoc against it to produce stubs for their target language.
  • The hypothetical version 6 of the protocol would live in internal/tfplugin6

It is particularly important that we change the package declaration in the .proto file before we release any updated plugins "for real" because the package name is part of the RPC protocol and therefore cannot be changed later.

Later we will probably move the actual proto file into a different documentation-oriented location, but for now keeping it in the directory where the Go package is generated keeps things simple with our existing generation process.

@ghost
Copy link

ghost commented Mar 31, 2020

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.

If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.

@ghost ghost locked and limited conversation to collaborators Mar 31, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant