From c236fd6b1d1246e466a42cd3ac7560d421670462 Mon Sep 17 00:00:00 2001 From: Protocol Buffer Team Date: Thu, 19 Dec 2024 22:40:39 +0000 Subject: [PATCH] Project import generated by Copybara. PiperOrigin-RevId: 708039275 Change-Id: I4e48375a5098096a0d69a3620e4d9a74b279735e --- content/news/2024-12-18.md | 30 +++++++++++++++++ content/news/_index.md | 2 ++ content/programming-guides/style.md | 6 ++-- content/reference/cpp/abseil.md | 4 +-- content/reference/rust/rust-generated.md | 32 +++++++++++++++---- .../devguide/proto/best-practices}/1-1-1.md | 0 .../doc/devguide/proto/best-practices}/api.md | 2 ++ .../proto/best-practices}/dos-donts.md | 4 +-- .../devguide/proto/best-practices/index.md | 6 ++-- 9 files changed, 70 insertions(+), 16 deletions(-) create mode 100644 content/news/2024-12-18.md rename {content/programming-guides => eng/doc/devguide/proto/best-practices}/1-1-1.md (100%) rename {content/programming-guides => eng/doc/devguide/proto/best-practices}/api.md (99%) rename {content/programming-guides => eng/doc/devguide/proto/best-practices}/dos-donts.md (99%) rename content/programming-guides/best-practices.md => eng/doc/devguide/proto/best-practices/index.md (59%) diff --git a/content/news/2024-12-18.md b/content/news/2024-12-18.md new file mode 100644 index 000000000..3cb8db458 --- /dev/null +++ b/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! diff --git a/content/news/_index.md b/content/news/_index.md index 14ce86a11..3c63c5ced 100644 --- a/content/news/_index.md +++ b/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::Reserve()` in v30 * [December 4, 2024](/news/2024-12-04) - `DebugString` diff --git a/content/programming-guides/style.md b/content/programming-guides/style.md index 8d4804336..8542aad86 100644 --- a/content/programming-guides/style.md +++ b/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} diff --git a/content/reference/cpp/abseil.md b/content/reference/cpp/abseil.md index 882da045f..63cb44641 100644 --- a/content/reference/cpp/abseil.md +++ b/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" +++ diff --git a/content/reference/rust/rust-generated.md b/content/reference/rust/rust-generated.md index 71ce8264a..5369b54a5 100644 --- a/content/reference/rust/rust-generated.md +++ b/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); } ``` diff --git a/content/programming-guides/1-1-1.md b/eng/doc/devguide/proto/best-practices/1-1-1.md similarity index 100% rename from content/programming-guides/1-1-1.md rename to eng/doc/devguide/proto/best-practices/1-1-1.md diff --git a/content/programming-guides/api.md b/eng/doc/devguide/proto/best-practices/api.md similarity index 99% rename from content/programming-guides/api.md rename to eng/doc/devguide/proto/best-practices/api.md index 3ba341af7..2b1c0cda2 100644 --- a/content/programming-guides/api.md +++ b/eng/doc/devguide/proto/best-practices/api.md @@ -1,3 +1,5 @@ + + +++ title = "API Best Practices" weight = 100 diff --git a/content/programming-guides/dos-donts.md b/eng/doc/devguide/proto/best-practices/dos-donts.md similarity index 99% rename from content/programming-guides/dos-donts.md rename to eng/doc/devguide/proto/best-practices/dos-donts.md index e1bc96541..71e9b21a5 100644 --- a/content/programming-guides/dos-donts.md +++ b/eng/doc/devguide/proto/best-practices/dos-donts.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). @@ -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). diff --git a/content/programming-guides/best-practices.md b/eng/doc/devguide/proto/best-practices/index.md similarity index 59% rename from content/programming-guides/best-practices.md rename to eng/doc/devguide/proto/best-practices/index.md index 8f7831c9a..79c782e28 100644 --- a/content/programming-guides/best-practices.md +++ b/eng/doc/devguide/proto/best-practices/index.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)