Merge pull request #203 from Logofile/sync

Documentation change

Author: Logofile

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<T>::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.

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<T>::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

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

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<Bar>* mutable_foo()`: Returns a pointer to the underlying
+-   `RepeatedPtrField<Bar>* 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.
 

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

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.

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.