1# Go support for Protocol Buffers
2
3[](https://pkg.go.dev/mod/github.com/golang/protobuf)
4[](https://travis-ci.org/golang/protobuf)
5
6This module
7([`github.com/golang/protobuf`](https://pkg.go.dev/mod/github.com/golang/protobuf))
8contains Go bindings for protocol buffers.
9
10It has been superseded by the
11[`google.golang.org/protobuf`](https://pkg.go.dev/mod/google.golang.org/protobuf)
12module, which contains an updated and simplified API,
13support for protobuf reflection, and many other improvements.
14We recommend that new code use the `google.golang.org/protobuf` module.
15
16Versions v1.4 and later of `github.com/golang/protobuf` are implemented
17in terms of `google.golang.org/protobuf`.
18Programs which use both modules must use at least version v1.4 of this one.
19
20See the
21[developer guide for protocol buffers in Go](https://developers.google.com/protocol-buffers/docs/gotutorial)
22for a general guide for how to get started using protobufs in Go.
23
24See
25[release note documentation](https://github.com/golang/protobuf/releases)
26for more information about individual releases of this project.
27
28See
29[documentation for the next major revision](https://pkg.go.dev/mod/google.golang.org/protobuf)
30for more information about the purpose, usage, and history of this project.
31
32## Package index
33
34Summary of the packages provided by this module:
35
36* [`proto`](https://pkg.go.dev/github.com/golang/protobuf/proto): Package
37 `proto` provides functions operating on protobuf messages such as cloning,
38 merging, and checking equality, as well as binary serialization and text
39 serialization.
40* [`jsonpb`](https://pkg.go.dev/github.com/golang/protobuf/jsonpb): Package
41 `jsonpb` serializes protobuf messages as JSON.
42* [`ptypes`](https://pkg.go.dev/github.com/golang/protobuf/ptypes): Package
43 `ptypes` provides helper functionality for protobuf well-known types.
44* [`ptypes/any`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/any):
45 Package `any` is the generated package for `google/protobuf/any.proto`.
46* [`ptypes/empty`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/empty):
47 Package `empty` is the generated package for `google/protobuf/empty.proto`.
48* [`ptypes/timestamp`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/timestamp):
49 Package `timestamp` is the generated package for
50 `google/protobuf/timestamp.proto`.
51* [`ptypes/duration`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/duration):
52 Package `duration` is the generated package for
53 `google/protobuf/duration.proto`.
54* [`ptypes/wrappers`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/wrappers):
55 Package `wrappers` is the generated package for
56 `google/protobuf/wrappers.proto`.
57* [`ptypes/struct`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/struct):
58 Package `structpb` is the generated package for
59 `google/protobuf/struct.proto`.
60* [`protoc-gen-go/descriptor`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go/descriptor):
61 Package `descriptor` is the generated package for
62 `google/protobuf/descriptor.proto`.
63* [`protoc-gen-go/plugin`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go/plugin):
64 Package `plugin` is the generated package for
65 `google/protobuf/compiler/plugin.proto`.
66* [`protoc-gen-go`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go):
67 The `protoc-gen-go` binary is a protoc plugin to generate a Go protocol
68 buffer package.
69
70## Reporting issues
71
72The issue tracker for this project
73[is located here](https://github.com/golang/protobuf/issues).
74
75Please report any issues with a sufficient description of the bug or feature
76request. Bug reports should ideally be accompanied by a minimal reproduction of
77the issue. Irreproducible bugs are difficult to diagnose and fix (and likely to
78be closed after some period of time). Bug reports must specify the version of
79the
80[Go protocol buffer module](https://github.com/protocolbuffers/protobuf-go/releases)
81and also the version of the
82[protocol buffer toolchain](https://github.com/protocolbuffers/protobuf/releases)
83being used.
84
85## Contributing
86
87This project is open-source and accepts contributions. See the
88[contribution guide](https://github.com/golang/protobuf/blob/master/CONTRIBUTING.md)
89for more information.
90
91## Compatibility
92
93This module and the generated code are expected to be stable over time. However,
94we reserve the right to make breaking changes without notice for the following
95reasons:
96
97* **Security:** A security issue in the specification or implementation may
98 come to light whose resolution requires breaking compatibility. We reserve
99 the right to address such issues.
100* **Unspecified behavior:** There are some aspects of the protocol buffer
101 specification that are undefined. Programs that depend on unspecified
102 behavior may break in future releases.
103* **Specification changes:** It may become necessary to address an
104 inconsistency, incompleteness, or change in the protocol buffer
105 specification, which may affect the behavior of existing programs. We
106 reserve the right to address such changes.
107* **Bugs:** If a package has a bug that violates correctness, a program
108 depending on the buggy behavior may break if the bug is fixed. We reserve
109 the right to fix such bugs.
110* **Generated additions**: We reserve the right to add new declarations to
111 generated Go packages of `.proto` files. This includes declared constants,
112 variables, functions, types, fields in structs, and methods on types. This
113 may break attempts at injecting additional code on top of what is generated
114 by `protoc-gen-go`. Such practice is not supported by this project.
115* **Internal changes**: We reserve the right to add, modify, and remove
116 internal code, which includes all unexported declarations, the
117 [`generator`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go/generator)
118 package, and all packages under
119 [`internal`](https://pkg.go.dev/github.com/golang/protobuf/internal).
120
121Any breaking changes outside of these will be announced 6 months in advance to
122[protobuf@googlegroups.com](https://groups.google.com/forum/#!forum/protobuf).
View as plain text