mirror of https://github.com/docker/cli.git
123 lines
6.2 KiB
Markdown
123 lines
6.2 KiB
Markdown
# Go support for Protocol Buffers
|
|
|
|
[](https://pkg.go.dev/mod/github.com/golang/protobuf)
|
|
[](https://travis-ci.org/golang/protobuf)
|
|
|
|
This module
|
|
([`github.com/golang/protobuf`](https://pkg.go.dev/mod/github.com/golang/protobuf))
|
|
contains Go bindings for protocol buffers.
|
|
|
|
It has been superseded by the
|
|
[`google.golang.org/protobuf`](https://pkg.go.dev/mod/google.golang.org/protobuf)
|
|
module, which contains an updated and simplified API,
|
|
support for protobuf reflection, and many other improvements.
|
|
We recommend that new code use the `google.golang.org/protobuf` module.
|
|
|
|
Versions v1.4 and later of `github.com/golang/protobuf` are implemented
|
|
in terms of `google.golang.org/protobuf`.
|
|
Programs which use both modules must use at least version v1.4 of this one.
|
|
|
|
See the
|
|
[developer guide for protocol buffers in Go](https://developers.google.com/protocol-buffers/docs/gotutorial)
|
|
for a general guide for how to get started using protobufs in Go.
|
|
|
|
See
|
|
[release note documentation](https://github.com/golang/protobuf/releases)
|
|
for more information about individual releases of this project.
|
|
|
|
See
|
|
[documentation for the next major revision](https://pkg.go.dev/mod/google.golang.org/protobuf)
|
|
for more information about the purpose, usage, and history of this project.
|
|
|
|
## Package index
|
|
|
|
Summary of the packages provided by this module:
|
|
|
|
* [`proto`](https://pkg.go.dev/github.com/golang/protobuf/proto): Package
|
|
`proto` provides functions operating on protobuf messages such as cloning,
|
|
merging, and checking equality, as well as binary serialization and text
|
|
serialization.
|
|
* [`jsonpb`](https://pkg.go.dev/github.com/golang/protobuf/jsonpb): Package
|
|
`jsonpb` serializes protobuf messages as JSON.
|
|
* [`ptypes`](https://pkg.go.dev/github.com/golang/protobuf/ptypes): Package
|
|
`ptypes` provides helper functionality for protobuf well-known types.
|
|
* [`ptypes/any`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/any):
|
|
Package `any` is the generated package for `google/protobuf/any.proto`.
|
|
* [`ptypes/empty`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/empty):
|
|
Package `empty` is the generated package for `google/protobuf/empty.proto`.
|
|
* [`ptypes/timestamp`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/timestamp):
|
|
Package `timestamp` is the generated package for
|
|
`google/protobuf/timestamp.proto`.
|
|
* [`ptypes/duration`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/duration):
|
|
Package `duration` is the generated package for
|
|
`google/protobuf/duration.proto`.
|
|
* [`ptypes/wrappers`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/wrappers):
|
|
Package `wrappers` is the generated package for
|
|
`google/protobuf/wrappers.proto`.
|
|
* [`ptypes/struct`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/struct):
|
|
Package `structpb` is the generated package for
|
|
`google/protobuf/struct.proto`.
|
|
* [`protoc-gen-go/descriptor`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go/descriptor):
|
|
Package `descriptor` is the generated package for
|
|
`google/protobuf/descriptor.proto`.
|
|
* [`protoc-gen-go/plugin`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go/plugin):
|
|
Package `plugin` is the generated package for
|
|
`google/protobuf/compiler/plugin.proto`.
|
|
* [`protoc-gen-go`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go):
|
|
The `protoc-gen-go` binary is a protoc plugin to generate a Go protocol
|
|
buffer package.
|
|
|
|
## Reporting issues
|
|
|
|
The issue tracker for this project
|
|
[is located here](https://github.com/golang/protobuf/issues).
|
|
|
|
Please report any issues with a sufficient description of the bug or feature
|
|
request. Bug reports should ideally be accompanied by a minimal reproduction of
|
|
the issue. Irreproducible bugs are difficult to diagnose and fix (and likely to
|
|
be closed after some period of time). Bug reports must specify the version of
|
|
the
|
|
[Go protocol buffer module](https://github.com/protocolbuffers/protobuf-go/releases)
|
|
and also the version of the
|
|
[protocol buffer toolchain](https://github.com/protocolbuffers/protobuf/releases)
|
|
being used.
|
|
|
|
## Contributing
|
|
|
|
This project is open-source and accepts contributions. See the
|
|
[contribution guide](https://github.com/golang/protobuf/blob/master/CONTRIBUTING.md)
|
|
for more information.
|
|
|
|
## Compatibility
|
|
|
|
This module and the generated code are expected to be stable over time. However,
|
|
we reserve the right to make breaking changes without notice for the following
|
|
reasons:
|
|
|
|
* **Security:** A security issue in the specification or implementation may
|
|
come to light whose resolution requires breaking compatibility. We reserve
|
|
the right to address such issues.
|
|
* **Unspecified behavior:** There are some aspects of the protocol buffer
|
|
specification that are undefined. Programs that depend on unspecified
|
|
behavior may break in future releases.
|
|
* **Specification changes:** It may become necessary to address an
|
|
inconsistency, incompleteness, or change in the protocol buffer
|
|
specification, which may affect the behavior of existing programs. We
|
|
reserve the right to address such changes.
|
|
* **Bugs:** If a package has a bug that violates correctness, a program
|
|
depending on the buggy behavior may break if the bug is fixed. We reserve
|
|
the right to fix such bugs.
|
|
* **Generated additions**: We reserve the right to add new declarations to
|
|
generated Go packages of `.proto` files. This includes declared constants,
|
|
variables, functions, types, fields in structs, and methods on types. This
|
|
may break attempts at injecting additional code on top of what is generated
|
|
by `protoc-gen-go`. Such practice is not supported by this project.
|
|
* **Internal changes**: We reserve the right to add, modify, and remove
|
|
internal code, which includes all unexported declarations, the
|
|
[`generator`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go/generator)
|
|
package, and all packages under
|
|
[`internal`](https://pkg.go.dev/github.com/golang/protobuf/internal).
|
|
|
|
Any breaking changes outside of these will be announced 6 months in advance to
|
|
[protobuf@googlegroups.com](https://groups.google.com/forum/#!forum/protobuf).
|