diff --git a/README.md b/README.md
index 64764efed..68dfa8cf1 100644
--- a/README.md
+++ b/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
diff --git a/fetch/README.md b/fetch/README.md
index 04ec78dbe..f5986483d 100644
--- a/fetch/README.md
+++ b/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;
 }
diff --git a/identify/README.md b/identify/README.md
index b64ef4887..2d7f141b2 100644
--- a/identify/README.md
+++ b/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;
diff --git a/kad-dht/README.md b/kad-dht/README.md
index e74d1d195..4367d9687 100644
--- a/kad-dht/README.md
+++ b/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 {
diff --git a/plaintext/README.md b/plaintext/README.md
index d94f16ea5..c0e47d6c9 100644
--- a/plaintext/README.md
+++ b/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;
diff --git a/pubsub/README.md b/pubsub/README.md
index 3a6116323..120b20657 100644
--- a/pubsub/README.md
+++ b/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
diff --git a/pubsub/gossipsub/gossipsub-v1.0-old.md b/pubsub/gossipsub/gossipsub-v1.0-old.md
index 98cb84915..a91003eb2 100644
--- a/pubsub/gossipsub/gossipsub-v1.0-old.md
+++ b/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;
diff --git a/pubsub/gossipsub/gossipsub-v1.0.md b/pubsub/gossipsub/gossipsub-v1.0.md
index 52118b5ee..db8fdbe0b 100644
--- a/pubsub/gossipsub/gossipsub-v1.0.md
+++ b/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;
diff --git a/pubsub/gossipsub/gossipsub-v1.1.md b/pubsub/gossipsub/gossipsub-v1.1.md
index 75c8a01a3..3d48d395d 100644
--- a/pubsub/gossipsub/gossipsub-v1.1.md
+++ b/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
diff --git a/relay/circuit-v1.md b/relay/circuit-v1.md
index 75bc85fc9..d11b6c34d 100644
--- a/relay/circuit-v1.md
+++ b/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 {
diff --git a/relay/circuit-v2.md b/relay/circuit-v2.md
index feb3fc99f..1e9f8d477 100644
--- a/relay/circuit-v2.md
+++ b/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;
diff --git a/rendezvous/README.md b/rendezvous/README.md
index 862eaeb44..66584c71f 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -191,6 +191,8 @@ topic.
 ### Protobuf
 
 ```protobuf
+syntax = "proto2";
+
 message Message {
   enum MessageType {
     REGISTER = 0;
diff --git a/tls/tls.md b/tls/tls.md
index e6ef6a1e2..e17d6640c 100644
--- a/tls/tls.md
+++ b/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;