Merge pull request protocolbuffers#260 from Logofile/sync

Logofile · web-flow · commit 951fee0f8b64 · 2025-06-09T16:01:14.000-04:00
Documentation change
diff --git a/content/best-practices/1-1-1.md b/content/best-practices/1-1-1.md
@@ -7,6 +7,14 @@ type = "docs"
 aliases = "/programming-guides/1-1-1"
 +++
 
+The "1-1-1" best practice advocates structuring definitions with one top-level
+entity (message, enum, or extension) per `.proto` file, corresponding to a
+single `proto_library` build rule. This approach promotes small, modular proto
+definitions. Key benefits include simplified refactoring, potentially improved
+build times, and smaller binary sizes due to minimized transitive dependencies.
+
+--------------------------------------------------------------------------------
+
 The 1-1-1 best practice is to keep every proto_library and .proto file as small
 as is reasonable, with the ideal being:
 
diff --git a/content/design-decisions/nullable-getters-setters.md b/content/design-decisions/nullable-getters-setters.md
@@ -12,6 +12,12 @@ C#, and Rust). While this does seem to be a helpful feature for folks using
 those languages, the design choice has tradeoffs which have led to the Protobuf
 team choosing not to implement them.
 
+Explicit presence is not a concept that directly maps to the traditional notion
+of nullability. It is subtle, but explicit presence philosophy is closer to "the
+fields are not nullable, but you can detect if the field was explicitly assigned
+a value or not. Normal access will see some default value if it is not assigned,
+but you can check if the field was actively written to or not, when needed."
+
 The biggest reason not to have nullable fields is the intended behavior of
 default values specified in a `.proto` file. By design, calling a getter on an
 unset field will return the default value of that field.
diff --git a/content/includes/version-tables.css b/content/includes/version-tables.css
@@ -95,36 +95,36 @@ table.version-chart td.active {
 /* latest release column */
 /*
  * How to advance the selection of the latest release:
- * Replace class 'y25q1' in the following selectors with 'y25q2' (the class
+ * Replace class 'y25q2' in the following selectors with 'y25q3' (the class
  * referring to the quarter of the next release). Please also update this
  * instruction as a courtesy to the next maintainer.
  */
 
 /* visually replace 'yyQq' heading with string 'Latest' */
-table.version-chart th.y25q1 span {
+table.version-chart th.y25q2 span {
   display: none;
 }
-table.version-chart th.y25q1::after {
+table.version-chart th.y25q2::after {
   content: "Latest"
 }
 
 /* draw a focus rectangle around the latest release column */
-table.version-chart th.y25q1 {
+table.version-chart th.y25q2 {
   border-top: 2px solid #e06666 !important;
   border-left: 2px solid #e06666 !important;
   border-right: 2px solid #e06666 !important;
 }
-table.version-chart td.y25q1 {
+table.version-chart td.y25q2 {
   font-weight: bold;
   border-left: 2px solid #e06666 !important;
   border-right: 2px solid #e06666 !important;
 }
-table.version-chart tr:last-child td.y25q1 {
+table.version-chart tr:last-child td.y25q2 {
   border-bottom: 2px solid #e06666 !important;
 }
 
 /* future release columns */
-table.version-chart td:not(:has(~ .y25q1)):not(.y25q1) {
+table.version-chart td:not(:has(~ .y25q2)):not(.y25q2) {
   font-style: italic;
 }
 
diff --git a/content/news/v21.md b/content/news/v21.md
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 21.x."
 type = "docs"
 +++
 
-The following announcements are specific to Version 21.x. For information
-presented chronologically, see [News](/news).
+The following announcements are specific to Version 21.x, which was released May
+25, 2022. For information presented chronologically, see
+[News](/news).
 
 ## Python Updates {#python-updates}
 
diff --git a/content/news/v22.md b/content/news/v22.md
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 22.x."
 type = "docs"
 +++
 
-The following announcements are specific to Version 22.x. For information
-presented chronologically, see [News](/news).
+The following announcements are specific to Version 22.x, which was released
+February 16, 2023. For information presented chronologically, see
+[News](/news).
 
 ### Changing Maven Release Candidate Artifact Names to Be More Idiomatic {#idiomatic}
 
diff --git a/content/news/v23.md b/content/news/v23.md
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 23.x."
 type = "docs"
 +++
 
-The following announcements are specific to Version 23.x. For information
-presented chronologically, see [News](/news).
+The following announcements are specific to Version 23.x, which was released May
+8, 2023. For information presented chronologically, see
+[News](/news).
 
 ## Changes to Ruby Generator {#ruby}
 
diff --git a/content/news/v24.md b/content/news/v24.md
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 24.x."
 type = "docs"
 +++
 
-The following announcements are specific to Version 24.x. For information
-presented chronologically, see [News](/news).
+The following announcements are specific to Version 24.x, which was released
+August 8, 2023. For information presented chronologically, see
+[News](/news).
 
 ## Stricter validation for `json_name` {#json-name}
 
diff --git a/content/news/v25.md b/content/news/v25.md
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 25.x."
 type = "docs"
 +++
 
-The following announcements are specific to Version 25.x. For information
-presented chronologically, see [News](/news).
+The following announcements are specific to Version 25.x, which was released
+November 1, 2023. For information presented chronologically, see
+[News](/news).
 
 ## Python Breaking Change
 
diff --git a/content/news/v26.md b/content/news/v26.md
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 26.x."
 type = "docs"
 +++
 
-The following announcements are specific to Version 26.x. For information
-presented chronologically, see [News](/news).
+The following announcements are specific to Version 26.x, which was released
+March 13, 2024. For information presented chronologically, see
+[News](/news).
 
 ## General Changes
 
diff --git a/content/news/v29.md b/content/news/v29.md
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 29.x."
 type = "docs"
 +++
 
-The following announcements are specific to Version 29.x. For information
-presented chronologically, see [News](/news).
+The following announcements are specific to Version 29.x, which was released
+November 27, 2024. For information presented chronologically, see
+[News](/news).
 
 ## Bazel and Proto Rules
 
diff --git a/content/news/v30.md b/content/news/v30.md
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 30.x."
 type = "docs"
 +++
 
-The following announcements are specific to Version 30.x. For information
-presented chronologically, see [News](/news).
+The following announcements are specific to Version 30.x, which was released
+March 4, 2025. For information presented chronologically, see
+[News](/news).
 
 The following sections cover planned breaking changes in the v30 release,
 expected in 2025 Q1. Also included are some changes that aren't breaking but may
diff --git a/content/news/v31.md b/content/news/v31.md
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 31.x."
 type = "docs"
 +++
 
-The following announcements are specific to Version 31.x. For information
-presented chronologically, see [News](/news).
+The following announcements are specific to Version 31.x, which was released May
+14, 2025. For information presented chronologically, see
+[News](/news).
 
 The following sections cover planned breaking changes in the v31 release,
 expected in 2025 Q2. Also included are some changes that aren't breaking but may
diff --git a/content/programming-guides/editions.md b/content/programming-guides/editions.md
@@ -1028,15 +1028,16 @@ following rules:
     preserved in the message, but how this is represented when the message is
     deserialized is language-dependent. Int fields always just preserve their
     value.
-*   Changing a single `optional` field or extension into a member of a **new**
+*   Changing a *single* `optional` field or extension into a member of a **new**
     `oneof` is binary compatible, however for some languages (notably, Go) the
     generated code's API will change in incompatible ways. For this reason,
     Google does not make such changes in its public APIs, as documented in
     [AIP-180](https://google.aip.dev/180#moving-into-oneofs). With
-    the same caveat about source-compatibility, moving multiple fields into a
-    new `oneof` may be safe if you are sure that no code sets more than one at a
-    time. Moving fields into an existing `oneof` is not safe. Likewise, changing
-    a single field `oneof` to an `optional` field or extension is safe.
+    the same caveat about source-compatibility, moving *multiple* fields into a
+    **new** `oneof` may be safe if you are sure that no code sets more than one
+    at a time. Likewise, changing a *single* field `oneof` to an `optional`
+    field or extension is safe. Moving *any* fields into an **existing** `oneof`
+    is **not** safe.
 *   Changing a field between a `map<K, V>` and the corresponding `repeated`
     message field is binary compatible (see [Maps](#maps), below, for the
     message layout and other restrictions). However, the safety of the change is
@@ -1183,8 +1184,8 @@ In C++, it would look something like:
 ```cpp
 UserContent user_content;
 user_content.AddExtension(kittens::kitten_videos, new kittens::Video());
-assert(1 == user_content.GetExtensionCount(kittens::kitten_videos));
-user_content.GetExtension(kittens::kitten_videos, 0);
+assert(1 == user_content.GetRepeatedExtension(kittens::kitten_videos).size());
+user_content.GetRepeatedExtension(kittens::kitten_videos)[0];
 ```
 
 ### Defining Extension Ranges {#defining-ranges}
diff --git a/content/programming-guides/encoding.md b/content/programming-guides/encoding.md
@@ -423,8 +423,9 @@ message Test6 {
 }
 ```
 
-Thus, maps are encoded exactly like a `repeated` message field: as a sequence of
-`LEN`-typed records, with two fields each.
+Thus, maps are encoded almost exactly like a `repeated` message field: as a
+sequence of `LEN`-typed records, with two fields each. The exception is that
+order is not guaranteed to be preserved with maps during serialization.
 
 ## Groups {#groups}
 
diff --git a/content/reference/protobuf/mime-types.md b/content/reference/protobuf/mime-types.md
@@ -0,0 +1,50 @@
++++
+title = "Protocol Buffer MIME Types"
+weight = 830
+linkTitle = "MIME Types"
+description = "Standard MIME types for Protobuf Serializations."
+type = "docs"
++++
+
+All Protobuf documents should have the MIME type `application` and the subtype
+`protobuf`, with the suffix `+json` for
+JSON
+encodings according to
+[the standard](https://datatracker.ietf.org/doc/draft-murray-dispatch-mime-protobuf/),
+followed by the following parameters:
+
+-   `encoding` should be set only to `binary`,
+    or `json`, denoting those respective
+    formats.
+    +   With subtype `protobuf+json`, `encoding` has the default `json` and
+        cannot be set to `binary`. With subtype `protobuf` (without `+json`),
+        `encoding` has the default `binary` and cannot be set to
+        `json`.
+    +   Use `+json` for JSON even in HTTP responses that use parser
+        breakers as a CORB mitigation.
+-   Set `charset` to `utf-8` for all JSONor Text Format encodings, and never set
+    it for binary encodings.
+    +   If `charset` is unspecified it is assumed to be UTF-8. It is preferable
+        to always specify a `charset` as that may prevent certain attack vectors
+        when protos are used in HTTP responses.
+-   Protobuf reserves the `version` parameter for potential future versioning of
+    our wire formats. Do not set it until a wire format is versioned.
+
+So the standard MIME types for common protobuf encodings are:
+
+-   `application/protobuf` for serialized binary protos.
+-   `application/protobuf+json; charset=utf-8` for JSON format protos.
+
+Services that read Protobuf should also handle `application/json`, which may be
+used to encode JSON format protos.
+
+Parsers must fail if MIME parameters (`encoding`, `charset`, or `version`) have
+unknown or illegal values.
+
+When binary protos are transacted over HTTP, Protobuf strongly recommends
+Base64-encoding them and setting `X-Content-Type-Options: nosniff` to prevent
+XSS, as it is possible for a Protobuf to parse as active content.
+
+It is acceptable to pass additional parameters to these MIME types if desired,
+such as a type URL which indicates the content schema; but the MIME type
+parameters ***must not*** include encoding options.
