all: update README.md

Change-Id: I60d9ccf1685e2e30327b5a4daf3c65b540c51e88
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/220679
Reviewed-by: Damien Neil <[email protected]>

Author: dsnet

README.md

@@ -1,281 +1,118 @@
-# Go support for Protocol Buffers - Google's data interchange format
+# Go support for Protocol Buffers
 
+[![GoDev](https://img.shields.io/static/v1?label=godev&message=reference&color=00add8)](https://pkg.go.dev/mod/github.com/golang/protobuf)
 [![Build Status](https://travis-ci.org/golang/protobuf.svg?branch=master)](https://travis-ci.org/golang/protobuf)
-[![GoDoc](https://godoc.org/github.com/golang/protobuf?status.svg)](https://godoc.org/github.com/golang/protobuf)
 
-Google's data interchange format.
-Copyright 2010 The Go Authors.
-https://github.com/golang/protobuf
-
-This package and the code it generates requires at least Go 1.9.
-
-This software implements Go bindings for protocol buffers.  For
-information about protocol buffers themselves, see
-	https://developers.google.com/protocol-buffers/
-
-## Installation ##
-
-To use this software, you must:
-- Install the standard C++ implementation of protocol buffers from
-	https://developers.google.com/protocol-buffers/
-- Of course, install the Go compiler and tools from
-	https://golang.org/
-  See
-	https://golang.org/doc/install
-  for details or, if you are using gccgo, follow the instructions at
-	https://golang.org/doc/install/gccgo
-- Grab the code from the repository and install the proto package.
-  The simplest way is to run `go get -u github.com/golang/protobuf/protoc-gen-go`.
-  The compiler plugin, protoc-gen-go, will be installed in $GOBIN,
-  defaulting to $GOPATH/bin.  It must be in your $PATH for the protocol
-  compiler, protoc, to find it.
-
-This software has two parts: a 'protocol compiler plugin' that
-generates Go source files that, once compiled, can access and manage
-protocol buffers; and a library that implements run-time support for
-encoding (marshaling), decoding (unmarshaling), and accessing protocol
-buffers.
-
-There is support for gRPC in Go using protocol buffers.
-See the note at the bottom of this file for details.
-
-There are no insertion points in the plugin.
-
-
-## Using protocol buffers with Go ##
-
-Once the software is installed, there are two steps to using it.
-First you must compile the protocol buffer definitions and then import
-them, with the support library, into your program.
-
-To compile the protocol buffer definition, run protoc with the --go_out
-parameter set to the directory you want to output the Go code to.
-
-	protoc --go_out=. *.proto
-
-The generated files will be suffixed .pb.go.  See the Test code below
-for an example using such a file.
-
-## Packages and input paths ##
-
-The protocol buffer language has a concept of "packages" which does not
-correspond well to the Go notion of packages. In generated Go code,
-each source `.proto` file is associated with a single Go package. The
-name and import path for this package is specified with the `go_package`
-proto option:
-
-	option go_package = "github.com/golang/protobuf/ptypes/any";
-
-The protocol buffer compiler will attempt to derive a package name and
-import path if a `go_package` option is not present, but it is
-best to always specify one explicitly.
-
-There is a one-to-one relationship between source `.proto` files and
-generated `.pb.go` files, but any number of `.pb.go` files may be
-contained in the same Go package.
-
-The output name of a generated file is produced by replacing the
-`.proto` suffix with `.pb.go` (e.g., `foo.proto` produces `foo.pb.go`).
-However, the output directory is selected in one of two ways.  Let
-us say we have `inputs/x.proto` with a `go_package` option of
-`github.com/golang/protobuf/p`. The corresponding output file may
-be:
-
-- Relative to the import path:
-
-```shell
-  protoc --go_out=. inputs/x.proto
-  # writes ./github.com/golang/protobuf/p/x.pb.go
-```
-
-  (This can work well with `--go_out=$GOPATH`.)
-
-- Relative to the input file:
-
-```shell
-protoc --go_out=paths=source_relative:. inputs/x.proto
-# generate ./inputs/x.pb.go
-```
-
-## Generated code ##
-
-The package comment for the proto library contains text describing
-the interface provided in Go for protocol buffers. Here is an edited
-version.
-
-The proto package converts data structures to and from the
-wire format of protocol buffers.  It works in concert with the
-Go source code generated for .proto files by the protocol compiler.
-
-A summary of the properties of the protocol buffer interface
-for a protocol buffer variable v:
-
-  - Names are turned from camel_case to CamelCase for export.
-  - There are no methods on v to set fields; just treat
-  	them as structure fields.
-  - There are getters that return a field's value if set,
-	and return the field's default value if unset.
-	The getters work even if the receiver is a nil message.
-  - The zero value for a struct is its correct initialization state.
-	All desired fields must be set before marshaling.
-  - A Reset() method will restore a protobuf struct to its zero state.
-  - Non-repeated fields are pointers to the values; nil means unset.
-	That is, optional or required field int32 f becomes F *int32.
-  - Repeated fields are slices.
-  - Helper functions are available to aid the setting of fields.
-	Helpers for getting values are superseded by the
-	GetFoo methods and their use is deprecated.
-		msg.Foo = proto.String("hello") // set field
-  - Constants are defined to hold the default values of all fields that
-	have them.  They have the form Default_StructName_FieldName.
-	Because the getter methods handle defaulted values,
-	direct use of these constants should be rare.
-  - Enums are given type names and maps from names to values.
-	Enum values are prefixed with the enum's type name. Enum types have
-	a String method, and a Enum method to assist in message construction.
-  - Nested groups and enums have type names prefixed with the name of
-  	the surrounding message type.
-  - Extensions are given descriptor names that start with E_,
-	followed by an underscore-delimited list of the nested messages
-	that contain it (if any) followed by the CamelCased name of the
-	extension field itself.  HasExtension, ClearExtension, GetExtension
-	and SetExtension are functions for manipulating extensions.
-  - Oneof field sets are given a single field in their message,
-	with distinguished wrapper types for each possible field value.
-  - Marshal and Unmarshal are functions to encode and decode the wire format.
-
-When the .proto file specifies `syntax="proto3"`, there are some differences:
-
-  - Non-repeated fields of non-message type are values instead of pointers.
-  - Enum types do not get an Enum method.
-
-Consider file test.proto, containing
-
-```proto
-	syntax = "proto2";
-	package example;
-
-	enum FOO { X = 17; };
-
-	message Test {
-	  required string label = 1;
-	  optional int32 type = 2 [default=77];
-	  repeated int64 reps = 3;
-	}
-```
-
-To create and play with a Test object from the example package,
-
-```go
-	package main
-
-	import (
-		"log"
-
-		"github.com/golang/protobuf/proto"
-		"path/to/example"
-	)
-
-	func main() {
-		test := &example.Test{
-			Label: proto.String("hello"),
-			Type:  proto.Int32(17),
-			Reps:  []int64{1, 2, 3},
-		}
-		data, err := proto.Marshal(test)
-		if err != nil {
-			log.Fatal("marshaling error: ", err)
-		}
-		newTest := &example.Test{}
-		err = proto.Unmarshal(data, newTest)
-		if err != nil {
-			log.Fatal("unmarshaling error: ", err)
-		}
-		// Now test and newTest contain the same data.
-		if test.GetLabel() != newTest.GetLabel() {
-			log.Fatalf("data mismatch %q != %q", test.GetLabel(), newTest.GetLabel())
-		}
-		// etc.
-	}
-```
-
-## Parameters ##
-
-To pass extra parameters to the plugin, use a comma-separated
-parameter list separated from the output directory by a colon:
-
-	protoc --go_out=plugins=grpc,import_path=mypackage:. *.proto
-
-- `paths=(import | source_relative)` - specifies how the paths of
-  generated files are structured. See the "Packages and imports paths"
-  section above. The default is `import`.
-- `plugins=plugin1+plugin2` - specifies the list of sub-plugins to
-  load. The only plugin in this repo is `grpc`.
-- `Mfoo/bar.proto=quux/shme` - declares that foo/bar.proto is
-  associated with Go package quux/shme.  This is subject to the
-  import_prefix parameter.
-
-The following parameters are deprecated and should not be used:
-
-- `import_prefix=xxx` - a prefix that is added onto the beginning of
-  all imports.
-- `import_path=foo/bar` - used as the package if no input files
-  declare `go_package`. If it contains slashes, everything up to the
-  rightmost slash is ignored.
-
-## gRPC Support ##
-
-If a proto file specifies RPC services, protoc-gen-go can be instructed to
-generate code compatible with gRPC (http://www.grpc.io/). To do this, pass
-the `plugins` parameter to protoc-gen-go; the usual way is to insert it into
-the --go_out argument to protoc:
-
-	protoc --go_out=plugins=grpc:. *.proto
-
-## Compatibility ##
-
-The library 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 security issues.
-- Unspecified behavior.  There are some aspects of the Protocol Buffers
-  specification that are undefined.  Programs that depend on such unspecified
-  behavior may break in future releases.
-- Specification errors or changes. If it becomes necessary to address an
-  inconsistency, incompleteness, or change in the Protocol Buffers
-  specification, resolving the issue could affect the meaning or legality of
-  existing programs.  We reserve the right to address such issues, including
-  updating the implementations.
-- Bugs.  If the library has a bug that violates the specification, a program
-  that depends on the buggy behavior may break if the bug is fixed.  We reserve
-  the right to fix such bugs.
-- Adding methods or fields to generated structs.  These may conflict with field
-  names that already exist in a schema, causing applications to break.  When the
-  code generator encounters a field in the schema that would collide with a
-  generated field or method name, the code generator will append an underscore
-  to the generated field or method name.
-- Adding, removing, or changing methods or fields in generated structs that
-  start with `XXX`.  These parts of the generated code are exported out of
-  necessity, but should not be considered part of the public API.
-- Adding, removing, or changing unexported symbols in generated code.
+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 should use at least version v1.4 of this one.
+
+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 `struct` 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
-[email protected].
-
-You should, whenever possible, use generated code created by the `protoc-gen-go`
-tool built at the same commit as the `proto` package.  The `proto` package
-declares package-level constants in the form `ProtoPackageIsVersionX`.
-Application code and generated code may depend on one of these constants to
-ensure that compilation will fail if the available version of the proto library
-is too old.  Whenever we make a change to the generated code that requires newer
-library support, in the same commit we will increment the version number of the
-generated code and declare a new package-level constant whose name incorporates
-the latest version number.  Removing a compatibility constant is considered a
-breaking change and would be subject to the announcement policy stated above.
-
-The `protoc-gen-go/generator` package exposes a plugin interface,
-which is used by the gRPC code generation. This interface is not
-supported and is subject to incompatible changes without notice.
+[[email protected]](https://groups.google.com/forum/#!forum/protobuf).