Skip to content

Documentation update #264

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
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
8 changes: 4 additions & 4 deletions content/best-practices/1-1-1.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,10 +34,10 @@ dependencies that may only be used by another message defined in the same file.

There are cases where the 1-1-1 ideal is not possible (circular dependencies),
not ideal (extremely conceptually coupled messages which have readability
benefits by being co-located), or where the some of the downsides don't apply
(when a .proto file has no imports, then there are no technical concerns about
the size of transitive dependencies). As with any best practice, use good
judgment for when to diverge from the guideline.
benefits by being co-located), or where some of the downsides don't apply (when
a .proto file has no imports, then there are no technical concerns about the
size of transitive dependencies). As with any best practice, use good judgment
for when to diverge from the guideline.

One place that modularity of proto schema files is important is when creating
gRPC
Expand Down
1 change: 1 addition & 0 deletions content/best-practices/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,4 @@ topics:
* [Proto Best Practices](/best-practices/dos-donts)
* [API Best Practices](/best-practices/api)
* [1-1-1 Rule](/best-practices/1-1-1)
* [Avoid Cargo Culting](/best-practices/no-cargo-cults)
5 changes: 0 additions & 5 deletions content/best-practices/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,10 @@ type = "docs"
aliases = "/programming-guides/api"
+++

Updated for proto3. Patches welcome!

This doc is a complement to
[Proto Best Practices](/best-practices/dos-donts). It's
not a prescription for Java/C++/Go and other APIs.

If you see a proto straying from these guidelines in a code review, point the
author to this topic and help spread the word.

{{% alert title="Note" color="note" %}}
These guidelines are just that and many have documented exceptions. For example,
if you're writing a performance-critical backend, you might want to sacrifice
Expand Down
227 changes: 227 additions & 0 deletions content/news/2025-06-27.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,227 @@
+++
title = "Changes Announced on June 27, 2025"
linkTitle = "June 27, 2025"
toc_hide = "true"
description = "Changes announced for Protocol Buffers on June 27, 2025."
type = "docs"
+++

## Edition 2024

We are planning to release Protobuf Editions in 32.x in Q3 2025.

These describe changes as we anticipate them being implemented, but due to the
flexible nature of software some of these changes may not land or may vary from
how they are described in this topic.

More documentation on Edition 2024 will be published in
[Feature Settings for Editions](/editions/features),
including information on migrating from Edition 2023.

## Changes to Existing Features {#changes}

This section details any existing features whose default settings will change in
Edition 2024.

### C++ string_type {#string_type}

The default for `string_type` feature, originally released in Edition 2023, will
change from `STRING` to `VIEW` in Edition 2024.

See
[`features.(pb.cpp).string_type`](/editions/features#string_type)
and [String View APIs](/reference/cpp/string-view) for
more information on this feature and its feature values.

## New Features {#new-features}

This section details any new features that will be introduced in Edition 2024.

### `enforce_naming_style` {#enforce_naming}

[`feature.enforce_naming_style`](/editions/features#enforce_naming)
enables strict naming style enforcement to ensure protos are round-trippable by
default with a feature value to opt-out to use legacy naming style.

### `default_symbol_visibility` {#default_symbol}

This feature controls whether the default symbol visibility of importable
symbols (such as messages and enums) is either:

* `export`: referenceable from other protos via import statements
* `local`: un-referenceable outside of current file

The default feature value `EXPORT_TOP_LEVEL` in Edition 2024 ensures top-level
symbols are export by default, whereas nested symbols are local by default.

This can be used along with the [`export` and `local` keywords](#export-local)
to explicitly annotate symbol visibility, also added in Edition 2024.

Symbol visibility only controls which symbols can be imported from other proto
files, but does not affect code-generation.

### C++: `enum_name_uses_string_view` {#enum_name}

Previously, all generated enum types provide the following function to obtain
the label out of an enum value, which has significant overhead to construct the
`std::string` instances at runtime:

```cpp
const std::string& Foo_Name(int);
```

The default feature value in Edition 2024 instead migrates this signature to
return `absl::string_view` to allow for better storage decoupling and potential
memory/CPU savings.

```cpp
absl::string_view Foo_Name(int);
```

Users should migrate their code to handle the new return-type following
[the migration guide](/support/migration#string_view-return-type).

See [String View APIs](/reference/cpp/string-view) for
more information.

### Java: `nest_in_file_class` {#nest_in}

This feature controls whether the Java generator will nest the generated class
in the Java generated file class.

The default value in Edition 2024 generates classes in their own files by
default, which is also the default behavior of the previous
`java_multiple_files = true` file option. This replaces `java_multiple_files`
which is removed in Edition 2024.

The default outer classname is also updated to always be the camel-cased
`.proto` filename suffixed with Proto by default (for example,
`foo/bar_baz.proto -> BarBazProto`). You can override this using the
`java_outer_classname` file option and replace the pre-Edition 2024 default of
`BarBaz` or `BarBazOuterClass` depending on the presence of conflicts.

### Java: `large_enum` {#large_enum}

This feature allows creation of large Java enums, extending beyond the enum
limit due to standard constant limits imposed by the Java language.

Creation of large enums is not enabled by default, but you can explicitly enable
it using this feature. Note that this feature replicates enum-like behavior but
has some notable differences (for example, switch statements are not supported).

## Grammar Changes {#grammar-changes}

### `import option` {#import-option}

Edition 2024 adds support for option imports using the syntax `import option`.

Unlike normal `import` statements, option imports import only custom options
defined in a `.proto` file, without importing other symbols.

This means that messages and enums are excluded from the option import. In the
following example, the `Bar` message cannot be used as a field type in
`foo.proto`, but options with type `Bar` can still be set.

Option imports must also come after any other import statements.

Example:

```proto
// bar.proto
edition = "2024";

import "google/protobuf/descriptor.proto";

message Bar {
bool bar = 1;
}

extend proto2.FileOptions {
bool file_opt1 = 5000;
Bar file_opt2 = 5001;
}
```

```proto
// foo.proto:
edition = "2024";

import option "bar.proto";

option (file_opt1) = true;
option (file_opt2) = {bar: true};

message Foo {
// Bar bar = 1; // This is not allowed
}
```

Option imports do not require generated code for its symbols and thus must be
provided as `option_deps` in `proto_library` instead of `deps`. This avoids
generating unreachable code.

```build
proto_library(
name = "foo",
srcs = ["foo.proto"],
option_deps = [":custom_option"]
)
```

Option imports and `option_deps` are strongly recommended when importing
protobuf language features and other custom options to avoid generating
unnecessary code.

`option_deps` requires Bazel 8 or later since the `native.proto_library` in
Bazel 7 does not support this.

This also replaces `import weak`, which is removed in Edition 2024.

### `export` / `local` Keywords {#export-local}

`export` and `local` keywords are added in Edition 2024 as modifiers for the
symbol visibility of importable symbols, from the default behavior specified by
the
[`default_symbol_visibility` feature](/editions/features#symbol-vis).

This controls which symbols can be imported from other proto files, but does not
affect code-generation.

In Edition 2024, these can be set on all message and enum symbols by default.
However, some values of the `default_symbol_visibility` feature further restrict
which symbols are exportable.

Example:

```proto
// Top-level symbols are exported by default in Edition 2024
local message LocalMessage {
// Nested symbols are local by default in Edition 2024
export enum ExportedNestedEnum {
UNKNOWN_EXPORTED_NESTED_ENUM_VALUE = 0;
}
}
```

### "import weak" and `weak` Field Option {#import-weak}

Weak imports are no longer allowed as of Edition 2024.

Most users previously relying on `import weak` to declare a “weak dependency” to
import custom options without generated code for C++ and Go should instead
migrate to use
[`import option`](/editions/overview#import-option)
instead.

### `ctype` Field Option {#ctype}

`ctype` field option is no longer allowed as of Edition 2024. Use the
[`features.(pb.cpp).string_type`](/editions/features#string_type)
feature, instead.

### `java_multiple_files` File Option {#java_multiple}

The `java_multiple_files` file option is removed in Edition 2024 in favor of the
new
[`features.nest_in_file_class`](/editions/features#java-nest_in_file)
Java feature.
3 changes: 3 additions & 0 deletions content/news/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ New news topics will also be published to the
The following news topics provide information in the reverse order in which it
was released.

* [June 27, 2025](/news/2025-06-27) - Edition 2024
* [March 18, 2025](/news/2025-03-18) - Dropping support
for Ruby 3.0
* [January 23, 2025](/news/2025-01-23) - Poison Java
Expand Down Expand Up @@ -96,6 +97,8 @@ release notes will be more complete. Also, not everything from the chronological
listing will be in these topics, as some content is not specific to a particular
release.

* [Version 32.x](/news/v32)
* [Version 31.x](/news/v31)
* [Version 30.x](/news/v30)
* [Version 29.x](/news/v29)
* [Version 26.x](/news/v26)
Expand Down
Loading