This documentation change fixes merge conflicts

Change-Id: I85acb6e88d5c425b694b0aaae5873f9bee6c6487

Author: Protocol Buffer Team

content/design-decisions/nullable-getters-setters.md

@@ -30,9 +30,9 @@ can't have defaults, there's no functional problem with this.
 As an example, consider this `.proto` file:
 
 ```proto
-message Msg { optional Child child = 1; }
-message Child { optional Grandchild grandchild = 1; }
-message Grandchild { optional int32 foo = 1 [default = 72]; }
+message Msg { Child child = 1; }
+message Child { Grandchild grandchild = 1; }
+message Grandchild { int32 foo = 1 [default = 72]; }
 ```
 
 and corresponding Kotlin getters:

content/editions/features.md

@@ -1052,15 +1052,15 @@ proto2         | `LEGACY`
 
 This feature determines how generated code should treat string fields. This
 replaces the `ctype` option from proto2 and proto3, and offers a new
-`string_view` feature. In Edition 2023, you can specify either `ctype` or
+`string_type` feature. In Edition 2023, you can specify either `ctype` or
 `string_type` on a field, but not both. In Edition 2024, the `ctype` option is
 removed.
 
 **Values available:**
 
-*   `VIEW`: Generates `string_view` accessors for the field. This will be the
-    default in a future edition.
-*   `CORD`: Generates `Cord` accessors for the field.
+*   `VIEW`: Generates `string_view` accessors for the field.
+*   `CORD`: Generates `Cord` accessors for the field. Not supported on extension
+    fields.
 *   `STRING`: Generates `string` accessors for the field.
 
 **Applicable to the following scopes:** File, Field

content/editions/overview.md

@@ -22,7 +22,11 @@ the default behavior for the edition you've selected. You can also override your
 overrides. The [section later in this topic on lexical scoping](#scoping) goes
 into more detail on that.
 
-*The latest released edition is 2024.*
+*The latest released edition is 2023.*
+
+The examples in this topic show edition 2024 features, but edition 2024 is
+currently in **pre-release review** and is not yet recommended for production
+code.
 
 ## Lifecycle of a Feature {#lifecycles}
 
@@ -176,7 +180,7 @@ package com.example;
 
 message Player {
   // in proto3, optional fields have explicit presence
-  optional string name = 1 [default = "N/A"];
+  optional string name = 1;
   // in proto3 no specified field rule defaults to implicit presence
   int32 id = 2;
   // in proto3 this is packed by default

content/getting-started/pythontutorial.md

@@ -293,6 +293,31 @@ Again, see the
 [`Message` API reference](https://googleapis.dev/python/protobuf/latest/google/protobuf/message.html#google.protobuf.message.Message)
 for a complete list.
 
+You can also easily serialize messages to and from JSON. The `json_format`
+module provides helpers for this:
+
+-   `MessageToJson(message)`: serializes the message to a JSON string.
+-   `Parse(json_string, message)`: parses a JSON string into the given message.
+
+For example:
+
+```python
+from google.protobuf import json_format
+import addressbook_pb2
+
+person = addressbook_pb2.Person()
+person.id = 1234
+person.name = "John Doe"
+person.email = "[email protected]"
+
+# Serialize to JSON
+json_string = json_format.MessageToJson(person)
+
+# Parse from JSON
+new_person = addressbook_pb2.Person()
+json_format.Parse(json_string, new_person)
+```
+
 {{% alert title="Important" color="warning" %}} **Protocol Buffers and Object Oriented Design**
 Protocol buffer classes are basically data holders (like structs in C) that
 don't provide additional functionality; they don't make good first class
@@ -464,12 +489,12 @@ One key feature provided by protocol message classes is *reflection*. You can
 iterate over the fields of a message and manipulate their values without writing
 your code against any specific message type. One very useful way to use
 reflection is for converting protocol messages to and from other encodings, such
-as XML or JSON. A more advanced use of reflection might be to find differences
-between two messages of the same type, or to develop a sort of "regular
-expressions for protocol messages" in which you can write expressions that match
-certain message contents. If you use your imagination, it's possible to apply
-Protocol Buffers to a much wider range of problems than you might initially
-expect!
+as XML or JSON (see [Parsing and Serialization](#parsing-serialization) for an
+example). A more advanced use of reflection might be to find differences between
+two messages of the same type, or to develop a sort of "regular expressions for
+protocol messages" in which you can write expressions that match certain message
+contents. If you use your imagination, it's possible to apply Protocol Buffers
+to a much wider range of problems than you might initially expect!
 
 Reflection is provided as part of the
 [`Message` interface](https://googleapis.dev/python/protobuf/latest/google/protobuf/message.html#google.protobuf.message.Message).

content/news/2023-04-28.md

@@ -8,12 +8,14 @@ type = "docs"
 
 ## Stricter validation for `json_name` {#json-name}
 
-v24 will forbid embedded null characters in the
+v24 will forbid zero unicode code points (`\u0000`) in the
 [`json_name` field option](/programming-guides/proto3/#json).
-Going forward, any valid Unicode characters will be accepted, **except**
-`\u0000`. Null will still be allowed in field values.
+Going forward, any valid Unicode characters will be accepted in `json_name`,
+**except** `\u0000`. `\0` characters will still be allowed to be used as values.
 
-Previously, the proto compiler allowed null characters, but support for this was
-inconsistent across languages and implementations. To fix this, we are
-clarifying the spec to say that null is not allowed in `json_name`, and will be
-rejected by the compiler.
+Previously, the proto compiler allowed `\0` characters in the `json_name` field
+option, but support for this was inconsistent across languages and
+implementations. To help prevent interoperability problems relating to
+mishandling of keys containing a `\0` character, we are clarifying the spec to
+say that `\0` is not allowed in `json_name`, and will be rejected by the
+compiler.

content/programming-guides/editions.md

@@ -1138,74 +1138,67 @@ There are two main reasons to use extensions:
 
 ### Example Extension {#ext-example}
 
-Let's look at an example extension:
+Using an extension is a two-step process. First, in the message you want to
+extend (the "container"), you must reserve a range of field numbers for
+extensions. Then, in a separate file, you define the extension field itself.
 
-```proto
-// file kittens/video_ext.proto
-
-import "kittens/video.proto";
-import "media/user_content.proto";
-
-package kittens;
+Here is an example that shows how to add an extension for kitten videos to a
+generic `UserContent` message.
 
-// This extension allows kitten videos in a media.UserContent message.
-extend media.UserContent {
-  // Video is a message imported from kittens/video.proto
-  repeated Video kitten_videos = 126;
-}
-```
+**Step 1: Reserve an extension range in the container message.**
 
-Note that the file defining the extension (`kittens/video_ext.proto`) imports
-the container message's file (`media/user_content.proto`).
-
-The container message must reserve a subset of its field numbers for extensions.
+The container message must use the `extensions` keyword to reserve a range of
+field numbers for others to use. It is a best practice to also add a
+`declaration` for the specific extension you plan to add. This declaration acts
+as a forward-declaration, making it easier for developers to discover extensions
+and avoid reusing field numbers.
 
 ```proto
-// file media/user_content.proto
+// media/user_content.proto
+edition = "2023";
 
 package media;
 
-// A container message to hold stuff that a user has created.
-message UserContent {
-  // Set verification to `DECLARATION` to enforce extension declarations for all
-  // extensions in this range.
-  extensions 100 to 199 [verification = DECLARATION];
-}
-```
-
-The container message's file (`media/user_content.proto`) defines the message
-`UserContent`, which reserves field numbers [100 to 199] for extensions. It is
-recommended to set `verification = DECLARATION` for the range to require
-declarations for all its extensions.
-
-When the new extension (`kittens/video_ext.proto`) is added, a corresponding
-declaration should be added to `UserContent` and `verification` should be
-removed.
-
-```
-// A container message to hold stuff that a user has created.
+// A container for user-created content.
 message UserContent {
   extensions 100 to 199 [
     declaration = {
       number: 126,
       full_name: ".kittens.kitten_videos",
       type: ".kittens.Video",
       repeated: true
-    },
-    // Ensures all field numbers in this extension range are declarations.
-    verification = DECLARATION
+    }
   ];
 }
 ```
 
-`UserContent` declares that field number `126` will be used by a `repeated`
-extension field with the fully-qualified name `.kittens.kitten_videos` and the
-fully-qualified type `.kittens.Video`. To learn more about extension
-declarations see
-[Extension Declarations](/programming-guides/extension_declarations).
+This declaration specifies the field number, full name, type, and cardinality of
+the extension that will be defined elsewhere.
+
+**Step 2: Define the extension in a separate file.**
+
+The extension itself is defined in a different `.proto` file, which typically
+focuses on a specific feature (like kitten videos). This avoids adding a
+dependency from the generic container to the specific feature.
+
+```proto
+// kittens/video_ext.proto
+edition = "2023";
+
+import "media/user_content.proto"; // Imports the container message
+import "kittens/video.proto";      // Imports the extension's message type
+
+package kittens;
+
+// This defines the extension field.
+extend media.UserContent {
+  repeated Video kitten_videos = 126;
+}
+```
 
-Note that the container message's file (`media/user_content.proto`) **does not**
-import the kitten_video extension definition (`kittens/video_ext.proto`)
+The `extend` block ties the new `kitten_videos` field back to the
+`media.UserContent` message, using the field number `126` that was reserved in
+the container.
 
 There is no difference in the wire-format encoding of extension fields as
 compared to a standard field with the same field number, type, and cardinality.

content/programming-guides/encoding.md

@@ -222,16 +222,15 @@ For example, `-500z` is the same as the varint `999`.
 
 ### Non-varint Numbers {#non-varints}
 
-Non-varint numeric types are simple -- `double` and `fixed64` have wire type
-`I64`, which tells the parser to expect a fixed eight-byte lump of data. We can
-specify a `double` record by writing `5: 25.4`, or a `fixed64` record with `6:
-200i64`. In both cases, omitting an explicit wire type implies the `I64` wire
-type.
+Non-varint numeric types are simple. `double` and `fixed64` have wire type
+`I64`, which tells the parser to expect a fixed eight-byte lump of data.
+`double` values are encoded in IEEE 754 double-precision format. We can specify
+a `double` record by writing `5: 25.4`, or a `fixed64` record with `6: 200i64`.
 
 Similarly `float` and `fixed32` have wire type `I32`, which tells it to expect
-four bytes instead. The syntax for these consists of adding an `i32` suffix.
-`25.4i32` will emit four bytes, as will `200i32`. Tag types are inferred as
-`I32`.
+four bytes instead. `float` values are encoded in IEEE 754 single-precision
+format. The syntax for these consists of adding an `i32` suffix. `25.4i32` will
+emit four bytes, as will `200i32`. Tag types are inferred as `I32`.
 
 ## Length-Delimited Records {#length-types}
 
@@ -529,11 +528,13 @@ value      := varint      for wire_type == VARINT,
 varint     := int32 | int64 | uint32 | uint64 | bool | enum | sint32 | sint64;
                 encoded as varints (sintN are ZigZag-encoded first)
 i32        := sfixed32 | fixed32 | float;
-                encoded as 4-byte little-endian;
-                memcpy of the equivalent C types (u?int32_t, float)
+                encoded as 4-byte little-endian (float is IEEE 754
+                single-precision); memcpy of the equivalent C types (u?int32_t,
+                float)
 i64        := sfixed64 | fixed64 | double;
-                encoded as 8-byte little-endian;
-                memcpy of the equivalent C types (u?int64_t, double)
+                encoded as 8-byte little-endian (double is IEEE 754
+                double-precision); memcpy of the equivalent C types (u?int64_t,
+                double)
 
 len-prefix := size (message | string | bytes | packed);
                 size encoded as int32 varint