Merge pull request #207 from Logofile/sync

Project import generated by Copybara.

Author: Logofile

content/news/2024-12-18.md

@@ -0,0 +1,30 @@
++++
+title = "Changes announced December 18, 2024"
+linkTitle = "December 18, 2024"
+toc_hide = "true"
+description = "Changes announced for Protocol Buffers on December 18, 2024."
+type = "docs"
++++
+
+## Go Protobuf: The new Opaque API
+
+Back in March 2020, we released the `google.golang.org/protobuf` module,
+[a major overhaul of the Go Protobuf API](https://go.dev/blog/protobuf-apiv2).
+This package introduced first-class
+[support for reflection](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect),
+a [`dynamicpb`](https://pkg.go.dev/google.golang.org/protobuf/types/dynamicpb)
+implementation and the
+[`protocmp`](https://pkg.go.dev/google.golang.org/protobuf/testing/protocmp)
+package for easier testing.
+
+That release introduced a new protobuf module with a new API. Today, we are
+releasing an additional API for generated code, meaning the Go code in the
+`.pb.go` files created by the protocol compiler (`protoc`). The blog post at
+https://go.dev/blog/protobuf-opaque explains our motivation for creating a new
+API and shows you how to use it in your projects.
+
+To be clear: We are not removing anything. We will continue to support the
+existing API for generated code, just like we still support the older protobuf
+module (by wrapping the `google.golang.org/protobuf` implementation). Go is
+[committed to backwards compatibility](https://go.dev/blog/compat) and this
+applies to Go Protobuf, too!

content/news/_index.md

@@ -20,6 +20,8 @@ New news topics will also be published to the
 The following news topics provide information in the reverse order in which it
 was released.
 
+*   [December 18, 2024](/news/2024-12-18) - Go Protobuf:
+    The new Opaque API
 *   [December 13, 2024](/news/2024-12-13) - Removing
     `MutableRepeatedFieldRef<T>::Reserve()` in v30
 *   [December 4, 2024](/news/2024-12-04) - `DebugString`

content/programming-guides/style.md

@@ -116,7 +116,7 @@ application that gets an unexpected enum value will mark the field as unset in
 the proto instance. The field accessor will then return the default value, which
 for enum fields is the first enum value. For more information on the unspecified
 enum value, see
-[the Proto Best Practices page](/programming-guides/dos-donts#unspecified-enum).
+[the Proto Best Practices page](/best-practices/dos-donts#unspecified-enum).
 
 ## Services {#services}
 
@@ -131,11 +131,11 @@ service FooService {
 ```
 
 For more service-related guidance, see
-[Create Unique Protos per Method](/programming-guides/api#unique-protos)
+[Create Unique Protos per Method](/best-practices/api#unique-protos)
 and
 [Don't Include Primitive Types in a Top-level Request or Response Proto](/programming-guides/api#dont-include-primitive-types)
 in the API Best Practices topic, and
-[Define Messages in Separate Files](/programming-guides/dos-donts.md#separate-files)
+[Define Messages in Separate Files](/best-practices/dos-donts.md#separate-files)
 in Proto Best Practices.
 
 ## Things to Avoid {#avoid}

content/reference/cpp/abseil.md

@@ -1,7 +1,7 @@
 +++
-title = "Asbseil Support"
+title = "Abseil Support"
 weight = 530
-linkTitle = "Asbseil Support"
+linkTitle = "Abseil Support"
 description = "The C++ implementation of Protocol Buffers has an explicit dependency on Abseil."
 type = "docs"
 +++

content/reference/rust/rust-generated.md

@@ -124,6 +124,9 @@ emitted for the owned message type (`Foo`). A subset of these functions with
 functions with either `&self` or `&mut self` will also be included on the
 `FooMut<'msg>`.
 
+To create an owned message type from a View / Mut type call `to_owned()`, which
+creates a deep copy.
+
 ## Nested Types {#nested-types}
 
 Given the message declaration:
@@ -324,6 +327,8 @@ enum Bar {
 The compiler generates a struct where each variant is an associated constant:
 
 ```rust
+#[derive(Clone, Copy, PartialEq, Eq, Hash)]
+#[repr(transparent)]
 pub struct Bar(i32);
 
 impl Bar {
@@ -366,6 +371,20 @@ enum Bar {
 }
 ```
 
+The compiler generates a struct where each variant is an associated constant:
+
+```rust
+#[derive(Clone, Copy, PartialEq, Eq, Hash)]
+#[repr(transparent)]
+pub struct Bar(i32);
+
+impl Bar {
+  pub const Unspecified: Bar = Bar(0);
+  pub const Value: Bar = Bar(1);
+  pub const OtherValue: Bar = Bar(2);
+}
+```
+
 For these field definitions:
 
 ```proto
@@ -536,14 +555,15 @@ enum FooBar {
 The compiler will generate:
 
 ```rust
-  #[derive(Clone, Copy, PartialEq, Eq)]
-  pub struct Foo(i32);
+  #[derive(Clone, Copy, PartialEq, Eq, Hash)]
+  #[repr(transparent)]
+  pub struct FooBar(i32);
 
   impl FooBar {
-    pub const Unknown: Foo = Foo(0);
-    pub const A: Foo = Foo(1);
-    pub const FooB: Foo = Foo(5);
-    pub const ValueC: Foo = Foo(1234);
+    pub const Unknown: FooBar = FooBar(0);
+    pub const A: FooBar = FooBar(1);
+    pub const FooB: FooBar = FooBar(5);
+    pub const ValueC: FooBar = FooBar(1234);
   }
 ```
 

content/programming-guides/1-1-1.md …c/devguide/proto/best-practices/1-1-1.mdcontent/programming-guides/1-1-1.md renamed to eng/doc/devguide/proto/best-practices/1-1-1.md content/programming-guides/1-1-1.md renamed to eng/doc/devguide/proto/best-practices/1-1-1.md

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

content/programming-guides/api.md …doc/devguide/proto/best-practices/api.mdcontent/programming-guides/api.md renamed to eng/doc/devguide/proto/best-practices/api.md content/programming-guides/api.md renamed to eng/doc/devguide/proto/best-practices/api.md

@@ -159,7 +159,7 @@ their own file with no dependencies. Then it's easy for anyone to use those
 types without introducing the transitive dependencies in your other proto files.
 
 For more on this topic, see
-[1-1-1 Rule](/programming-guides/1-1-1).
+[1-1-1 Rule](/best-practices/1-1-1).
 
 <a id="dont-change-the-default-value-of-a-field"></a>
 
@@ -259,4 +259,4 @@ problems.
 
 This document lists only changes that are extremely likely to cause breakage.
 For higher-level guidance on how to craft proto APIs that grow gracefully see
-[API Best Practices](/programming-guides/api).
+[API Best Practices](/best-practices/api).

content/programming-guides/dos-donts.md …vguide/proto/best-practices/dos-donts.mdcontent/programming-guides/dos-donts.md renamed to eng/doc/devguide/proto/best-practices/dos-donts.md content/programming-guides/dos-donts.md renamed to eng/doc/devguide/proto/best-practices/dos-donts.md

@@ -9,6 +9,6 @@ no_list = "true"
 Best practices content for defining and using protos exists in the following
 topics:
 
-*   [Proto Best Practices](/programming-guides/dos-donts)
-*   [API Best Practices](/programming-guides/api)
-*   [1-1-1 Rule](/programming-guides/1-1-1)
+*   [Proto Best Practices](/best-practices/dos-donts)
+*   [API Best Practices](/best-practices/api)
+*   [1-1-1 Rule](/best-practices/1-1-1)