Merge pull request #506 from libp2p/marco/proto3

Recommend proto3

README.md

@@ -70,7 +70,14 @@ and are used throughout the system.
 These specs define wire protocols that are used by libp2p for connectivity,
 security, multiplexing, and other purposes.
 
-The protocols described below all use [protocol buffers](https://developers.google.com/protocol-buffers/docs/proto?hl=en) (aka protobuf) to define message schemas. Version `proto2` is used unless stated otherwise.
+The protocols described below all use [protocol
+buffers](https://developers.google.com/protocol-buffers/docs/proto?hl=en) (aka
+protobuf) to define message schemas.
+
+Existing protocols may use `proto2`, and continue to use them. `proto3` is
+recommended for new protocols. `proto3` is a simplification of `proto2` and
+removes some footguns. For context and a discussion around `proto3` vs `proto2`,
+see [#465](https://github.com/libp2p/specs/issues/465).
 
 - [ping][spec_ping] - Ping protocol
 - [autonat][spec_autonat] - NAT detection

fetch/README.md

@@ -88,6 +88,8 @@ The libp2p protocol ID for this protocol is `/libp2p/fetch/0.0.1`
 The messages in the Fetch protocol use on of the following protobufs (proto3 syntax):
 
 ```
+syntax = "proto2";
+
 message FetchRequest {
 	string identifier = 1;
 }

identify/README.md

@@ -73,6 +73,7 @@ whose values have changed.
 ## The Identify Message
 
 ```protobuf
+syntax = "proto2";
 message Identify {
   optional string protocolVersion = 5;
   optional string agentVersion = 6;

kad-dht/README.md

@@ -401,6 +401,8 @@ bytes, encoded as an unsigned variable length integer as defined by the
 All RPC messages conform to the following protobuf:
 
 ```protobuf
+syntax = "proto2";
+
 // Record represents a dht record that contains a value
 // for a key value pair
 message Record {

plaintext/README.md

@@ -84,6 +84,8 @@ The `PublicKey` message uses the same definition [specified in the peer id
 spec][peer-id-spec-pubkey-message]. For reference, it is defined as follows:
 
 ``` protobuf
+syntax = "proto2";
+
 enum KeyType {
 	RSA = 0;
 	Ed25519 = 1;

pubsub/README.md

@@ -90,6 +90,7 @@ messages between participating peers.
 The `RPC` protobuf is as follows:
 
 ```protobuf
+syntax = "proto2";
 message RPC {
 	repeated SubOpts subscriptions = 1;
 	repeated Message publish = 2;
@@ -112,6 +113,7 @@ false signifies 'unsubscribe'.
 The RPC message can contain zero or more messages of type 'Message'. The Message protobuf looks like this:
 
 ```protobuf
+syntax = "proto2";
 message Message {
 	optional string from = 1;
 	optional bytes data = 2;
@@ -341,6 +343,7 @@ and may be removed once used.
 The `TopicDescriptor` protobuf is as follows:
 
 ```protobuf
+syntax = "proto2";
 message TopicDescriptor {
 	optional string name = 1;
 	// AuthOpts and EncOpts are unused as of Oct 2018, but

pubsub/gossipsub/gossipsub-v1.0-old.md

@@ -375,6 +375,8 @@ control messages. The four control messages are `ControlIHave` for `IHAVE` messa
 The protobuf is as follows:
 
 ```protobuf
+syntax = "proto2";
+
 message RPC {
     // ...
 	optional ControlMessage control = 3;

pubsub/gossipsub/gossipsub-v1.0.md

@@ -506,6 +506,8 @@ The four control messages are `ControlIHave` for [`IHAVE`](#ihave) messages,
 The protobuf is as follows:
 
 ```protobuf
+syntax = "proto2";
+
 message RPC {
     // ... see definition in pubsub interface spec
 	optional ControlMessage control = 3;

pubsub/gossipsub/gossipsub-v1.1.md

@@ -129,6 +129,7 @@ In this case, the pruned peer will have to rely on the ambient peer discovery se
 The `ControlPrune` message is extended with a `peers` field as follows.
 
 ```protobuf
+syntax = "proto2";
 message ControlPrune {
 	optional string topicID = 1;
 	repeated PeerInfo peers = 2; // gossipsub v1.1 PX

relay/circuit-v1.md

@@ -140,6 +140,8 @@ We start the description of the Wire format by illustrating a possible flow scen
 Every message in the relay protocol uses the following protobuf:
 
 ```
+syntax = "proto2";
+
 message CircuitRelay {
 
   enum Status {

relay/circuit-v2.md

@@ -347,7 +347,8 @@ The voucher itself is a [Signed Envelope](../RFC/0002-signed-envelopes.md).
 The envelope domain is `libp2p-relay-rsvp` and uses the multicodec code `0x0302`.
 
 The payload of the envelope has the following form, in canonicalized protobuf format:
-```
+```protobuf
+syntax = "proto2";
 message Voucher {
   required bytes relay = 1;
   required bytes peer = 2;
@@ -363,7 +364,8 @@ The wire representation is canonicalized, where elements of the message are writ
 
 ## Protobuf
 
-```
+```protobuf
+syntax = "proto2";
 message HopMessage {
   enum Type {
     RESERVE = 0;

rendezvous/README.md

@@ -198,6 +198,8 @@ topic.
 ### Protobuf
 
 ```protobuf
+syntax = "proto2";
+
 message Message {
   enum MessageType {
     REGISTER = 0;

tls/tls.md

@@ -104,6 +104,8 @@ SignedKey ::= SEQUENCE {
 The publicKey field of `SignedKey` contains the public host key of the endpoint, encoded using the following protobuf:
 
 ```protobuf
+syntax = "proto2";
+
 enum KeyType {
 	RSA = 0;
 	Ed25519 = 1;