Merge pull request #264 from Logofile/sync

Documentation update

Author: Logofile

content/best-practices/1-1-1.md

@@ -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

content/best-practices/_index.md

@@ -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)

content/best-practices/api.md

@@ -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

content/news/2025-06-27.md

@@ -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.

content/news/_index.md

@@ -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
@@ -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)