Test copybara

mkruskal-google · copybara-github · commit edacfce261e9 · 2025-09-18T12:31:14.000-07:00
PiperOrigin-RevId: 808677109
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
@@ -37,4 +37,4 @@ jobs:
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./public
-          cname: protobuf.dev
+          cname: protobuf.dev
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,5 +1,7 @@
 # How to Contribute
 
+blah
+
 We'd love to accept your patches and contributions to this project. There are
 just a few small guidelines you need to follow.
 
diff --git a/content/includes/custom.css b/content/includes/custom.css
@@ -0,0 +1,3 @@
+.g3doc-duckie-link-button {
+    display: none;
+}
diff --git a/content/programming-guides/enum.md b/content/programming-guides/enum.md
@@ -51,7 +51,7 @@ question:
 ## Implications of *Closed* Enums
 
 The behavior of *closed* enums has unexpected consequences when parsing a
-repeated field. When a `repeated Enum` field is parsed all unknown values will
+repeated field. When a `repeated Enum` field is parsed, all unknown values will
 be placed in the
 [unknown field](/programming-guides/proto3/#unknowns)
 set. When it is serialized those unknown values will be written again, *but not
diff --git a/content/programming-guides/serialization-not-canonical.md b/content/programming-guides/serialization-not-canonical.md
@@ -5,6 +5,11 @@ description = "Explains how serialization works and why it is not canonical."
 type = "docs"
 +++
 
+<!--*
+# Document freshness: For more information, see go/fresh-source.
+freshness: { owner: 'esrauch' reviewed: '2025-01-09' }
+*-->
+
 Many people want a serialized proto to canonically represent the contents of
 that proto. Use cases include:
 
diff --git a/content/reference/go/opaque-faq.md b/content/reference/go/opaque-faq.md
@@ -35,9 +35,9 @@ make the Opaque API the default.
 
 ## How Do I Enable the New Opaque API for My Messages? {#enable}
 
-With Protobuf Edition 2023 (current at the time of writing), you can select the
-Opaque API by setting the `api_level` editions feature to `API_OPAQUE` in your
-`.proto` file. This can be set per file or per message:
+Starting with Protobuf Edition 2023, you can select the Opaque API by setting
+the `api_level` editions feature to `API_OPAQUE` in your `.proto` file. This can
+be set per file or per message:
 
 ```proto
 edition = "2023";
@@ -50,7 +50,7 @@ option features.(pb.go).api_level = API_OPAQUE;
 message LogEntry { … }
 ```
 
-Protobuf Edition 2024 will default to the Opaque API, meaning you will not need
+Protobuf Edition 2024 defaults to the Opaque API, meaning you will not need
 extra imports or options anymore:
 
 ```proto
@@ -61,8 +61,6 @@ package log;
 message LogEntry { … }
 ```
 
-The release date estimate for Protobuf Edition 2024 is early 2025.
-
 For your convenience, you can also override the default API level with a
 `protoc` command-line flag:
 
diff --git a/content/reference/go/opaque-migration.md b/content/reference/go/opaque-migration.md
@@ -66,6 +66,7 @@ To install the migration tool, use:
 
 ```
 go install google.golang.org/open2opaque@latest
+go install golang.org/x/tools/cmd/goimports@latest
 ```
 
 {{% alert title="Note" color="info" %}}If
diff --git a/content/reference/java/java-generated.md b/content/reference/java/java-generated.md
@@ -674,6 +674,15 @@ class Any {
   // Checks whether this Any message’s payload is the given type.
   public <T extends Message> boolean is(class<T> clazz);
 
+  // Checks whether this Any message’s payload has the same type as the given
+  // message.
+  public boolean isSameTypeAs(Message message);
+
+  // Unpacks Any into a message with the same type as the given messsage.
+  // Throws exception if the type doesn’t match or parsing the payload fails.
+  public <T extends Message> T unpackSameTypeAs(T message)
+      throws InvalidProtocolBufferException;
+
   // Unpacks Any into the given message type. Throws exception if
   // the type doesn’t match or parsing the payload has failed.
   public <T extends Message> T unpack(class<T> clazz)
diff --git a/content/reference/protobuf/google.protobuf.md b/content/reference/protobuf/google.protobuf.md
@@ -433,6 +433,12 @@ Enum type definition
       </td>
       <td>The source syntax.</td>
     </tr>
+    <tr>
+      <td><code>edition</code></td>
+      <td><code>string</code>
+      </td>
+      <td>The source edition if <code>syntax</code> is <code>SYNTAX_EDITIONS</code>.</td>
+    </tr>
   </tbody>
 </table>
 
@@ -1231,6 +1237,10 @@ The syntax in which a protocol buffer element is defined.
       <td><code>SYNTAX_PROTO3</code></td>
       <td>Syntax <code>proto3</code>.</td>
     </tr>
+    <tr>
+      <td><code>SYNTAX_EDITIONS</code></td>
+      <td>Syntax uses the <code>edition</code> construct.</td>
+    </tr>
   </tbody>
 </table>
 
diff --git a/content/reference/ruby/ruby-generated.md b/content/reference/ruby/ruby-generated.md
@@ -13,10 +13,6 @@ read the language guides for
 [editions](/programming-guides/editions) before reading
 this document.
 
-The protocol compiler for Ruby emits Ruby source files that use a DSL to define
-the message schema. However the DSL is still subject to change. In this guide we
-only describe the API of the generated messages, and not the DSL.
-
 ## Compiler Invocation {#invocation}
 
 The protocol buffer compiler produces Ruby output when invoked with the
diff --git a/content/reference/rust/rust-generated.md b/content/reference/rust/rust-generated.md
@@ -75,50 +75,89 @@ following associated functions and methods:
 ### Associated Functions
 
 *   `fn new() -> Self`: Creates a new instance of `Foo`.
-*   `fn parse(data: &[u8]) -> Result<Self, protobuf::ParseError>`: Parses `data`
-    and returns an instance of `Foo` if `data` holds a valid wire format
-    representation of `Foo`. Otherwise, the function returns an error.
-
-### Methods
 
+### Traits
+
+For a number of reasons, including gencode size, name collision problems, and
+gencode stability, most common functionality on messages is implemented on
+traits instead of as inherent implementations.
+
+Most users should import our prelude, which only includes traits and our
+`proto!` macro and no other types (`use protobuf::prelude::*`). If you would
+rather avoid preludes, you can always import the specific traits as needed (see
+the
+<!-- TODO: replace `4.32.0-prerelease` with `latest` once we do a stable release -->
+[documentation here](https://docs.rs/protobuf/4.32.0-release/protobuf/trait.Message.html)
+for the names and definitions of the traits if you want to import them
+directly).
+
+*   `fn parse(data: &[u8]) -> Result<Self, ParseError>`: Parses a new instance
+    of a message.
+*   `fn parse_dont_enforce_required(data: &[u8]) -> Result<Self, ParseError>`:
+    Same as `parse` but does not fail on missing proto2 `required` fields.
+*   `fn clear(&mut self)`: Clears message.
 *   `fn clear_and_parse(&mut self, data: &[u8]) -> Result<(), ParseError>`:
-    Clearing and parsing into existing instance (`protobuf::ClearAndParse`
-    trait).
+    Clearing and parsing into an existing instance.
+*   `fn clear_and_parse_dont_enforce_required(&mut self, data: &[u8]) ->
+    Result<(), ParseError>`: Same as `parse` but does not fail on missing proto2
+    `required` fields.
 *   `fn serialize(&self) -> Result<Vec<u8>, SerializeError>`: Serializes the
     message to Protobuf wire format. Serialization can fail but rarely will.
-    Failure reasons include exceeding the maximum message size, insufficient
-    memory, and required fields (proto2) that are unset (`protobuf::Serialize`
-    trait).
-*   `fn clear(&mut self)`: Clears message (`protobuf::Clear` trait).
-*   `fn merge_from(&mut self, other)`: Merges `self` with `other`
-    (`protobuf::MergeFrom` trait).
+    Failure reasons include if the representation exceeds the maximum encoded
+    message size (must be less than 2 GiB), and `required` fields (proto2) that
+    are unset.
+*   `fn take_from(&mut self, other)`: Moves `other` into `self`, discarding any
+    previous state that `self` contained.
+*   `fn copy_from(&mut self, other)`: Copies `other` into `self`, discarding any
+    previous state that `self` contained. `other` is unmodified.
+*   `fn merge_from(&mut self, other)`: Merges `other` into `self`.
 *   `fn as_view(&self) -> FooView<'_>`: Returns an immutable handle (view) to
     `Foo`. This is further covered in the section on proxy types.
 *   `fn as_mut(&mut self) -> FooMut<'_>`: Returns a mutable handle (mut) to
     `Foo`. This is further covered in the section on proxy types.
 
-`Foo` implements the following traits:
+`Foo` additionally implements the following std traits:
 
-*   `protobuf::ClearAndParse`
-*   `protobuf::Clear`
-*   `protobuf::CopyFrom`
-*   `protobuf::MergeFrom`
-*   `protobuf::Parse`
-*   `protobuf::Serialize`
-*   `protobuf::TakeFrom`
 *   `std::fmt::Debug`
 *   `std::default::Default`
 *   `std::clone::Clone`
-*   `std::ops::Drop`
 *   `std::marker::Send`
 *   `std::marker::Sync`
 
-#### Message Proxy Types {#message-proxy-types}
+### Fluently Create New Instances {#proto-macro}
+
+The API design of setters follows our established Protobuf idioms, but the
+verbosity when constructing new instances is a mild pain point in certain other
+languages. To mitigate this, we offer a `proto!` macro, which can be used to
+more-succinctly/fluently create new instances.
 
-As a consequence of the requirement to support multiple kernels with a single
-Rust API, we cannot in some situations use native Rust references (`&T` and
-`&mut T`), but instead, we need to express these concepts using types - `View`s
-and `Mut`s. These situations are shared and mutable references to:
+For example, instead of writing this:
+
+```
+let mut msg = SomeMsg::new();
+msg.set_x(1);
+msg.set_y("hello");
+msg.some_submessage_mut().set_z(42);
+```
+
+This macro can be used to write it as follows:
+
+```
+let msg = proto!(SomeMsg {
+  x: 1,
+  y: "hello",
+  some_submsg: SomeSubmsg {
+    z: 42
+  }
+});
+```
+
+### Message Proxy Types {#message-proxy-types}
+
+For a number of technical reasons, we have chosen to avoid using native Rust
+references (`&T` and `&mut T`) in certain cases. Instead, we need to express
+these concepts using types - `View`s and `Mut`s. These situations are shared and
+mutable references to:
 
 *   Messages
 *   Repeated fields
@@ -140,6 +179,10 @@ functions with either `&self` or `&mut self` will also be included on the
 To create an owned message type from a View / Mut type call `to_owned()`, which
 creates a deep copy.
 
+See the corresponding section in our
+[design decisions](/reference/rust/rust-design-decisions#view-mut-proxy-types)
+documentation for more discussion about why this choice was made.
+
 ## Nested Types {#nested-types}
 
 Given the message declaration:
diff --git a/package-lock.json b/package-lock.json

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+.g3doc-duckie-link-button {`
	`2`	`+ display: none;`
	`3`	`+}`