From 8cd6715b9f61a7e321141c6519e428d949bf4f4d Mon Sep 17 00:00:00 2001 From: Protocol Buffer Team Date: Fri, 13 Dec 2024 19:41:07 +0000 Subject: [PATCH] This documentation change includes the following: * Adds a News article for a v30 change to reflection-based functionality in C++ * Clarifies some style guide text about enum values * Adds a link to the recommendations for Java proto names to the Java Generated Code topic * Updates the enum examples in the Rust Generated Code topic to confirm to naming best practices * Adds clarifying information about how long code generated will be supported by the runtime PiperOrigin-RevId: 705950787 Change-Id: I8d25344a867975220f8f5fcae9e07de42450c1f7 --- content/news/2024-12-13.md | 18 +++++++++++++++ content/news/v30.md | 11 +++++++++ content/programming-guides/style.md | 16 +++++++++---- content/reference/cpp/cpp-generated.md | 2 +- content/reference/java/java-generated.md | 3 +++ content/reference/rust/rust-generated.md | 23 +++++++++++++------ .../cross-version-runtime-guarantee.md | 4 ++++ 7 files changed, 65 insertions(+), 12 deletions(-) create mode 100644 content/news/2024-12-13.md diff --git a/content/news/2024-12-13.md b/content/news/2024-12-13.md new file mode 100644 index 000000000..d54dd2837 --- /dev/null +++ b/content/news/2024-12-13.md @@ -0,0 +1,18 @@ ++++ +title = "Changes announced December 13, 2024" +linkTitle = "December 13, 2024" +toc_hide = "true" +description = "Changes announced for Protocol Buffers on December 13, 2024." +type = "docs" ++++ + +## Removing a Reflection-related Function + +In v30.x, we are removing the following reflection-related function: +`MutableRepeatedFieldRef::Reserve()`. + +An upcoming performance improvement in +[`RepeatedPtrField`](/reference/cpp/api-docs/google.protobuf.repeated_field#RepeatedPtrField) +is incompatible with this API. The improvement is projected to accelerate +repeated access to the elements of `RepeatedPtrField`, in particular and +especially sequential access. diff --git a/content/news/v30.md b/content/news/v30.md index da9d2e2c4..2f8d0ed43 100644 --- a/content/news/v30.md +++ b/content/news/v30.md @@ -55,6 +55,17 @@ be parseable by Protobuf TextFormat Parsers. Read more about this in the [news article released November 21, 2024](/news/2024-11-21). +### Removing a a Reflection-related Function {#removing-mutable-repeated} + +We are removing the following reflection-related function: +`MutableRepeatedFieldRef::Reserve()`. + +An upcoming performance improvement in +[`RepeatedPtrField`](/reference/cpp/api-docs/google.protobuf.repeated_field#RepeatedPtrField) +is incompatible with this API. The improvement is projected to accelerate +repeated access to the elements of `RepeatedPtrField`, in particular and +especially sequential access. + ### Remove Deprecated APIs {#remove-deprecated} v30 will remove the following public runtime APIs, which have been marked diff --git a/content/programming-guides/style.md b/content/programming-guides/style.md index 413ace225..8d4804336 100644 --- a/content/programming-guides/style.md +++ b/content/programming-guides/style.md @@ -98,10 +98,18 @@ enum FooBar { } ``` -Each enum value should end with a semicolon, not a comma. Prefer prefixing enum -values instead of surrounding them in an enclosing message. Since some languages -don't support an enum being defined inside a "struct" type, this ensures a -consistent approach across binding languages. +Each enum value should end with a semicolon, not a comma. + +Since the enum values are semantically not scoped by their containing enum name, +the same value name in two sibling enums is not allowed. A name collision issue +is especially a risk for top level enums, since in that case their siblings may +be defined in another file which has the same package. To avoid these risks, it +is strongly recommended to either prefix every value with the enum name or to +nest the enum inside a containing message. + +Prefer using top-level enums with prefixed values over nesting them inside a +message. Since some languages don't support an enum being defined inside a +"struct" type, this ensures a consistent approach across binding languages. The zero value enum should have the suffix `UNSPECIFIED`, because a server or application that gets an unexpected enum value will mark the field as unset in diff --git a/content/reference/cpp/cpp-generated.md b/content/reference/cpp/cpp-generated.md index 6b3cd9194..3b4a1b6a7 100644 --- a/content/reference/cpp/cpp-generated.md +++ b/content/reference/cpp/cpp-generated.md @@ -658,7 +658,7 @@ The compiler will generate the following accessor methods: [`RepeatedPtrField`](/reference/cpp/api-docs/google.protobuf.repeated_field#RepeatedPtrField) that stores the field's elements. This container class provides STL-like iterators and other methods. -- `RepeatedPtrField* mutable_foo()`: Returns a pointer to the underlying +- `RepeatedPtrField* mutable_bar()`: Returns a pointer to the underlying mutable `RepeatedPtrField` that stores the field's elements. This container class provides STL-like iterators and other methods. diff --git a/content/reference/java/java-generated.md b/content/reference/java/java-generated.md index a3f5a8610..25c745790 100644 --- a/content/reference/java/java-generated.md +++ b/content/reference/java/java-generated.md @@ -132,6 +132,9 @@ are not expected to start with a backwards domain name. ## Messages {#message} +If you are designing a new protocol buffer schema, see +[the recommendations for Java proto names](/reference/java/java-proto-names). + Given a simple message declaration: ```proto diff --git a/content/reference/rust/rust-generated.md b/content/reference/rust/rust-generated.md index 452bb2ae1..71ce8264a 100644 --- a/content/reference/rust/rust-generated.md +++ b/content/reference/rust/rust-generated.md @@ -525,9 +525,10 @@ Additionally, it will generate the two accessors: Given an enum definition like: ```proto -enum Foo { - VALUE_A = 0; - VALUE_B = 5; +enum FooBar { + FOO_BAR_UNKNOWN = 0; + FOO_BAR_A = 1; + FOO_B = 5; VALUE_C = 1234; } ``` @@ -536,16 +537,24 @@ The compiler will generate: ```rust #[derive(Clone, Copy, PartialEq, Eq)] - pub struct Foo(i32); - impl Foo { - pub const ValueA: Foo = Foo(0); - pub const ValueB: Foo = Foo(5); + 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); } ``` +Note that for values with a prefix that matches the enum, the prefix will be +stripped; this is done to improve ergonomics. Enum values are commonly prefixed +with the enum name to avoid name collisions between sibling enums (which follow +the semantics of C++ enums where the values are not scoped by their containing +enum). Since the generated Rust consts are scoped within the `impl`, the +additional prefix, which is beneficial to add in .proto files, would be +redundant in Rust. + ## Extensions (proto2 only) {#extensions} A Rust API for extensions is currently a work in progress. diff --git a/content/support/cross-version-runtime-guarantee.md b/content/support/cross-version-runtime-guarantee.md index 9ac26e23c..af7daa3e8 100644 --- a/content/support/cross-version-runtime-guarantee.md +++ b/content/support/cross-version-runtime-guarantee.md @@ -42,6 +42,10 @@ compatibility window for major versions. Code generated for a major version V (full version: V.x.y) will be supported by protobuf runtimes of version V and V+1. +Prior to this policy, code generated for 3.22.x+ (release ~1 year prior to major +version 4) will still be supported by protobuf runtimes of version 3 and 4. +Users with older gencode should upgrade to the latest gencode from 3.25.x. + Protobuf will not support using gencode from version V with runtime >= V+2 and will be using a "poison pill" mechanism to fail with a clear error message when a software assembly attempts to use such a configuration.