Documentation change

content/best-practices/api.md

@@ -1,5 +1,3 @@
-<!-- go/markdown -->
-
 +++
 title = "API Best Practices"
 weight = 100

content/getting-started/kotlintutorial.md

@@ -37,7 +37,7 @@ ways to solve this problem:
 
 -   Use kotlinx.serialization. This does not work very well if you need to share
     data with applications written in C++ or Python. kotlinx.serialization has a
-    [protobuf mode](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/formats.md#protobuf-experimental),
+    [protobuf mode](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/formats#protobuf-experimental),
     but this does not offer the full features of protocol buffers.
 -   You can invent an ad-hoc way to encode the data items into a single
     string -- such as encoding 4 ints as "12:3:-23:67". This is a simple and

content/programming-guides/editions.md

@@ -329,12 +329,91 @@ A scalar message field can have one of the following types – the table shows t
 type specified in the `.proto` file, and the corresponding type in the
 automatically generated class:
 
-<div style="overflow:auto;width:100%;">
-  <table style="width: 110%;">
+<div>
+  <table>
     <tbody>
       <tr>
-        <th>.proto Type</th>
+        <th>Proto Type</th>
         <th>Notes</th>
+      </tr>
+      <tr>
+        <td>double</td>
+        <td></td>
+      </tr>
+      <tr>
+        <td>float</td>
+        <td></td>
+      </tr>
+      <tr>
+        <td>int32</td>
+        <td>Uses variable-length encoding. Inefficient for encoding negative
+        numbers – if your field is likely to have negative values, use sint32
+        instead.</td>
+      </tr>
+      <tr>
+        <td>int64</td>
+        <td>Uses variable-length encoding. Inefficient for encoding negative
+        numbers – if your field is likely to have negative values, use sint64
+        instead.</td>
+      </tr>
+      <tr>
+        <td>uint32</td>
+        <td>Uses variable-length encoding.</td>
+      </tr>
+      <tr>
+        <td>uint64</td>
+        <td>Uses variable-length encoding.</td>
+      </tr>
+      <tr>
+        <td>sint32</td>
+        <td>Uses variable-length encoding. Signed int value. These more
+        efficiently encode negative numbers than regular int32s.</td>
+      </tr>
+      <tr>
+        <td>sint64</td>
+        <td>Uses variable-length encoding. Signed int value. These more
+        efficiently encode negative numbers than regular int64s.</td>
+      </tr>
+      <tr>
+        <td>fixed32</td>
+        <td>Always four bytes. More efficient than uint32 if values are often
+        greater than 2<sup>28</sup>.</td>
+      </tr>
+      <tr>
+        <td>fixed64</td>
+        <td>Always eight bytes. More efficient than uint64 if values are often
+        greater than 2<sup>56</sup>.</td>
+      </tr>
+      <tr>
+        <td>sfixed32</td>
+        <td>Always four bytes.</td>
+      </tr>
+      <tr>
+        <td>sfixed64</td>
+        <td>Always eight bytes.</td>
+      </tr>
+      <tr>
+        <td>bool</td>
+        <td></td>
+      </tr>
+      <tr>
+        <td>string</td>
+        <td>A string must always contain UTF-8 encoded or 7-bit ASCII text, and cannot
+        be longer than 2<sup>32</sup>.</td>
+      </tr>
+      <tr>
+        <td>bytes</td>
+        <td>May contain any arbitrary sequence of bytes no longer than 2<sup>32</sup>.</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+<div>
+  <table style="width: 100%;overflow-x: scroll;">
+    <tbody>
+      <tr>
+        <th>Proto Type</th>
         <th>C++ Type</th>
         <th>Java/Kotlin Type<sup>[1]</sup></th>
         <th>Python Type<sup>[3]</sup></th>
@@ -347,7 +426,6 @@ automatically generated class:
       </tr>
       <tr>
         <td>double</td>
-        <td></td>
         <td>double</td>
         <td>double</td>
         <td>float</td>
@@ -360,7 +438,6 @@ automatically generated class:
       </tr>
       <tr>
         <td>float</td>
-        <td></td>
         <td>float</td>
         <td>float</td>
         <td>float</td>
@@ -373,9 +450,6 @@ automatically generated class:
       </tr>
       <tr>
         <td>int32</td>
-        <td>Uses variable-length encoding. Inefficient for encoding negative
-        numbers – if your field is likely to have negative values, use sint32
-        instead.</td>
         <td>int32_t</td>
         <td>int</td>
         <td>int</td>
@@ -388,9 +462,6 @@ automatically generated class:
       </tr>
       <tr>
         <td>int64</td>
-        <td>Uses variable-length encoding. Inefficient for encoding negative
-        numbers – if your field is likely to have negative values, use sint64
-        instead.</td>
         <td>int64_t</td>
         <td>long</td>
         <td>int/long<sup>[4]</sup></td>
@@ -403,7 +474,6 @@ automatically generated class:
       </tr>
       <tr>
         <td>uint32</td>
-        <td>Uses variable-length encoding.</td>
         <td>uint32_t</td>
         <td>int<sup>[2]</sup></td>
         <td>int/long<sup>[4]</sup></td>
@@ -416,7 +486,6 @@ automatically generated class:
       </tr>
       <tr>
         <td>uint64</td>
-        <td>Uses variable-length encoding.</td>
         <td>uint64_t</td>
         <td>long<sup>[2]</sup></td>
         <td>int/long<sup>[4]</sup></td>
@@ -429,8 +498,6 @@ automatically generated class:
       </tr>
       <tr>
         <td>sint32</td>
-        <td>Uses variable-length encoding. Signed int value. These more
-        efficiently encode negative numbers than regular int32s.</td>
         <td>int32_t</td>
         <td>int</td>
         <td>int</td>
@@ -443,8 +510,6 @@ automatically generated class:
       </tr>
       <tr>
         <td>sint64</td>
-        <td>Uses variable-length encoding. Signed int value. These more
-        efficiently encode negative numbers than regular int64s.</td>
         <td>int64_t</td>
         <td>long</td>
         <td>int/long<sup>[4]</sup></td>
@@ -457,8 +522,6 @@ automatically generated class:
       </tr>
       <tr>
         <td>fixed32</td>
-        <td>Always four bytes. More efficient than uint32 if values are often
-        greater than 2<sup>28</sup>.</td>
         <td>uint32_t</td>
         <td>int<sup>[2]</sup></td>
         <td>int/long<sup>[4]</sup></td>
@@ -471,8 +534,6 @@ automatically generated class:
       </tr>
       <tr>
         <td>fixed64</td>
-        <td>Always eight bytes. More efficient than uint64 if values are often
-        greater than 2<sup>56</sup>.</td>
         <td>uint64_t</td>
         <td>long<sup>[2]</sup></td>
         <td>int/long<sup>[4]</sup></td>
@@ -485,7 +546,6 @@ automatically generated class:
       </tr>
       <tr>
         <td>sfixed32</td>
-        <td>Always four bytes.</td>
         <td>int32_t</td>
         <td>int</td>
         <td>int</td>
@@ -498,7 +558,6 @@ automatically generated class:
       </tr>
       <tr>
         <td>sfixed64</td>
-        <td>Always eight bytes.</td>
         <td>int64_t</td>
         <td>long</td>
         <td>int/long<sup>[4]</sup></td>
@@ -511,7 +570,6 @@ automatically generated class:
       </tr>
       <tr>
         <td>bool</td>
-        <td></td>
         <td>bool</td>
         <td>boolean</td>
         <td>bool</td>
@@ -524,8 +582,6 @@ automatically generated class:
       </tr>
       <tr>
         <td>string</td>
-        <td>A string must always contain UTF-8 encoded or 7-bit ASCII text, and cannot
-        be longer than 2<sup>32</sup>.</td>
         <td>string</td>
         <td>String</td>
         <td>str/unicode<sup>[5]</sup></td>
@@ -538,10 +594,9 @@ automatically generated class:
       </tr>
       <tr>
         <td>bytes</td>
-        <td>May contain any arbitrary sequence of bytes no longer than 2<sup>32</sup>.</td>
         <td>string</td>
         <td>ByteString</td>
-        <td>str (Python 2)<br/>bytes (Python 3)</td>
+        <td>str (Python 2), bytes (Python 3)</td>
         <td>[]byte</td>
         <td>String (ASCII-8BIT)</td>
         <td>ByteString</td>
@@ -1440,7 +1495,17 @@ language in the relevant [API reference](/reference/).
     ```
 
 *   If the parser encounters multiple members of the same oneof on the wire,
-    only the last member seen is used in the parsed message.
+    only the last member seen is used in the parsed message. When parsing data
+    on the wire, starting at the beginning of the bytes, evaluate the next
+    value, and apply the following parsing rules:
+
+    *   First, check if a *different* field in the same oneof is currently set,
+        and if so clear it.
+
+    *   Then apply the contents as though the field was not in a oneof:
+
+        *   A primitive will overwrite any value already set
+        *   A message will merge into any value already set
 
 *   Extensions are not supported for oneof.
 

content/programming-guides/field_presence.md

@@ -179,6 +179,12 @@ basic types (numeric, string, bytes, and enums), either. Oneof fields
 affirmatively expose presence, although the same set of hazzer methods may not
 generated as in proto2 APIs.
 
+This default behavior of not tracking presence without the `optional` label is
+different from the proto2 behavior. We reintroduced
+[explicit presence](/editions/features#field_presence) as
+the default in edition 2023. We recommend using the `optional` field with proto3
+unless you have a specific reason not to.
+
 Under the *implicit presence* discipline, the default value is synonymous with
 "not present" for purposes of serialization. To notionally "clear" a field (so
 it won't be serialized), an API user would set it to the default value.

content/programming-guides/proto-limits.md

@@ -24,8 +24,7 @@ Empty message extended by singular fields (such as Boolean):
 
 *   ~4100 fields (proto2)
 
-Extensions are supported
-[only by proto2](/programming-guides/version-comparison#extensionsany).
+Extensions are not supported in proto3.
 
 To test this limitation, create a proto message with more than the upper bound
 number of fields and compile using a Java proto rule. The limit comes from JVM