Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions content/news/2024-12-13.md
Original file line number Diff line number Diff line change
@@ -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.
11 changes: 11 additions & 0 deletions content/news/v30.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
16 changes: 12 additions & 4 deletions content/programming-guides/style.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion content/reference/cpp/cpp-generated.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
3 changes: 3 additions & 0 deletions content/reference/java/java-generated.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
23 changes: 16 additions & 7 deletions content/reference/rust/rust-generated.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
```
Expand All @@ -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.
Expand Down
4 changes: 4 additions & 0 deletions content/support/cross-version-runtime-guarantee.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 &gt;= 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.
Expand Down