From 64d62795850f1369a4b5e03641aca7b66af23649 Mon Sep 17 00:00:00 2001 From: Protocol Buffer Team Date: Mon, 30 Dec 2024 19:27:06 +0000 Subject: [PATCH] This documentation changes includes the following: * Moves best practices topics into a subsection * Fixes formatting for Notes and Warnings * Adds default-value syntax to the examples in the overview topic * Updates the C++ types in the scalar values tables * Updates the Arenas topic to reflect the replacement of `CreateMessage()` with `Create()` * Corrects the package section in the Java Generated topic * Updates the proto3 spec to add the `optional` field type modifier PiperOrigin-RevId: 710759644 Change-Id: I44fa6fe46103003f12f64dfa06dc58758cd638cd --- .../proto => content}/best-practices/1-1-1.md | 0 .../best-practices/_index.md | 0 .../proto => content}/best-practices/api.md | 0 .../best-practices/dos-donts.md | 0 content/editions/implementation.md | 11 ++- content/editions/overview.md | 8 +- content/programming-guides/editions.md | 28 +++--- .../extension_declarations.md | 14 ++- content/programming-guides/field_presence.md | 14 +-- content/programming-guides/proto2.md | 20 ++-- content/programming-guides/proto3.md | 20 ++-- content/reference/cpp/arenas.md | 98 ++++++++++--------- content/reference/cpp/cpp-generated.md | 4 +- content/reference/dart/dart-generated.md | 11 ++- content/reference/go/faq.md | 8 +- content/reference/go/opaque-migration.md | 8 +- content/reference/java/java-generated.md | 11 ++- content/reference/protobuf/proto3-spec.md | 2 +- .../reference/rust/building-rust-protos.md | 7 +- content/support/version-support.md | 7 +- 20 files changed, 152 insertions(+), 119 deletions(-) rename {eng/doc/devguide/proto => content}/best-practices/1-1-1.md (100%) rename eng/doc/devguide/proto/best-practices/index.md => content/best-practices/_index.md (100%) rename {eng/doc/devguide/proto => content}/best-practices/api.md (100%) rename {eng/doc/devguide/proto => content}/best-practices/dos-donts.md (100%) diff --git a/eng/doc/devguide/proto/best-practices/1-1-1.md b/content/best-practices/1-1-1.md similarity index 100% rename from eng/doc/devguide/proto/best-practices/1-1-1.md rename to content/best-practices/1-1-1.md diff --git a/eng/doc/devguide/proto/best-practices/index.md b/content/best-practices/_index.md similarity index 100% rename from eng/doc/devguide/proto/best-practices/index.md rename to content/best-practices/_index.md diff --git a/eng/doc/devguide/proto/best-practices/api.md b/content/best-practices/api.md similarity index 100% rename from eng/doc/devguide/proto/best-practices/api.md rename to content/best-practices/api.md diff --git a/eng/doc/devguide/proto/best-practices/dos-donts.md b/content/best-practices/dos-donts.md similarity index 100% rename from eng/doc/devguide/proto/best-practices/dos-donts.md rename to content/best-practices/dos-donts.md diff --git a/content/editions/implementation.md b/content/editions/implementation.md index b8e839242..478f2d9cf 100644 --- a/content/editions/implementation.md +++ b/content/editions/implementation.md @@ -188,11 +188,12 @@ language-appropriate naming: delimited encoding * `EnumDescriptor::is_closed` - Whether or not a field is closed -**Note:** In most languages, the message encoding feature is still currently -signaled by `TYPE_GROUP` and required fields still have `LABEL_REQUIRED` set. -This is not ideal, and was done to make downstream migrations easier. -Eventually, these should be migrated to the appropriate helpers and -`TYPE_MESSAGE/LABEL_OPTIONAL`. +{{% alert title="Note" color="note" %}} In +most languages, the message encoding feature is still currently signaled by +`TYPE_GROUP` and required fields still have `LABEL_REQUIRED` set. This is not +ideal, and was done to make downstream migrations easier. Eventually, these +should be migrated to the appropriate helpers and +`TYPE_MESSAGE/LABEL_OPTIONAL`.{{% /alert %}} Downstream users should migrate to these new helpers instead of using syntax directly. The following class of existing descriptor APIs should ideally be diff --git a/content/editions/overview.md b/content/editions/overview.md index 87192f11b..514978349 100644 --- a/content/editions/overview.md +++ b/content/editions/overview.md @@ -99,7 +99,7 @@ package com.example; message Player { // in proto2, optional fields have explicit presence - optional string name = 1; + optional string name = 1 [default = "N/A"]; // proto2 still supports the problematic "required" field rule required int32 id = 2; // in proto2 this is not packed by default @@ -129,7 +129,7 @@ package com.example; message Player { // fields have explicit presence, so no explicit setting needed - string name = 1; + string name = 1 [default = "N/A"]; // to match the proto2 behavior, LEGACY_REQUIRED is set at the field level int32 id = 2 [features.field_presence = LEGACY_REQUIRED]; // to match the proto2 behavior, EXPANDED is set at the field level @@ -169,7 +169,7 @@ package com.example; message Player { // in proto3, optional fields have explicit presence - optional string name = 1; + optional string name = 1 [default = "N/A"]; // in proto3 no specified field rule defaults to implicit presence int32 id = 2; // in proto3 this is packed by default @@ -199,7 +199,7 @@ package com.example; message Player { // fields have explicit presence, so no explicit setting needed - string name = 1; + string name = 1 [default = "N/A"]; // to match the proto3 behavior, IMPLICIT is set at the field level int32 id = 2 [features.field_presence = IMPLICIT]; // PACKED is the default state, and is provided just for illustration diff --git a/content/programming-guides/editions.md b/content/programming-guides/editions.md index ff4e7d2c7..fe873282b 100644 --- a/content/programming-guides/editions.md +++ b/content/programming-guides/editions.md @@ -376,7 +376,7 @@ automatically generated class: Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. - int32 + int32_t int int int32 @@ -391,7 +391,7 @@ automatically generated class: Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. - int64 + int64_t long int/long[4] int64 @@ -404,7 +404,7 @@ automatically generated class: uint32 Uses variable-length encoding. - uint32 + uint32_t int[2] int/long[4] uint32 @@ -417,7 +417,7 @@ automatically generated class: uint64 Uses variable-length encoding. - uint64 + uint64_t long[2] int/long[4] uint64 @@ -431,7 +431,7 @@ automatically generated class: sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. - int32 + int32_t int int int32 @@ -445,7 +445,7 @@ automatically generated class: sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. - int64 + int64_t long int/long[4] int64 @@ -459,7 +459,7 @@ automatically generated class: fixed32 Always four bytes. More efficient than uint32 if values are often greater than 228. - uint32 + uint32_t int[2] int/long[4] uint32 @@ -473,7 +473,7 @@ automatically generated class: fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 256. - uint64 + uint64_t long[2] int/long[4] uint64 @@ -486,7 +486,7 @@ automatically generated class: sfixed32 Always four bytes. - int32 + int32_t int int int32 @@ -499,7 +499,7 @@ automatically generated class: sfixed64 Always eight bytes. - int64 + int64_t long int/long[4] int64 @@ -696,8 +696,8 @@ field default. You can define aliases by assigning the same value to different enum constants. To do this you need to set the `allow_alias` option to `true`. Otherwise, the protocol buffer compiler generates a warning message when aliases are -found. Though all alias values are valid during deserialization, the first value -is always used when serializing. +found. Though all alias values are valid for serialization, only the first value +is used when deserializing. ```proto enum EnumAllowingAlias { @@ -716,6 +716,8 @@ enum EnumNotAllowingAlias { } ``` +### Enum Constants {#enum-constants} + Enumerator constants must be in the range of a 32-bit integer. Since `enum` values use [varint encoding](/programming-guides/encoding) on the @@ -725,6 +727,8 @@ these `enum`s can be reused in any message definition in your `.proto` file. You can also use an `enum` type declared in one message as the type of a field in a different message, using the syntax `_MessageType_._EnumType_`. +### Language-specific Enum Implementations {#enum-language} + When you run the protocol buffer compiler on a `.proto` that uses an `enum`, the generated code will have a corresponding `enum` for Java, Kotlin, or C++, or a special `EnumDescriptor` class for Python that's used to create a set of diff --git a/content/programming-guides/extension_declarations.md b/content/programming-guides/extension_declarations.md index e68a3c275..3fc145b78 100644 --- a/content/programming-guides/extension_declarations.md +++ b/content/programming-guides/extension_declarations.md @@ -15,9 +15,11 @@ freshness: { owner: 'shaod' reviewed: '2024-09-16' } This page describes in detail what extension declarations are, why we need them, and how we use them. -**NOTE:** Proto3 does not support extensions (except for +{{% alert title="Note" color="note" %}} +Proto3 does not support extensions (except for [declaring custom options](/programming-guides/proto3/#customoptions)). -Extensions are fully supported in proto2 and editions though. +Extensions are fully supported in proto2 and editions +though.{{% /alert %}} If you need an introduction to extensions, read this [extensions guide](https://protobuf.dev/programming-guides/proto2/#extensions) @@ -74,9 +76,11 @@ This syntax has the following semantics: (`Foo`) with this name or number, we enforce that the number, type, and full name of the extension match what is forward-declared here. -**WARNING:** Avoid using declarations for extension range groups such as -`extensions 4, 999`. It is unclear which extension range the declarations apply -to, and it is currently unsupported. +{{% alert title="Warning" color="warning" %}} +Avoid using declarations for extension range groups such as `extensions 4, 999`. +It is unclear which extension range the declarations apply to, and it is +currently +unsupported.{{% /alert %}} The extension declarations expect two extension fields with different packages: diff --git a/content/programming-guides/field_presence.md b/content/programming-guides/field_presence.md index 27e962fca..cc30c2fb1 100644 --- a/content/programming-guides/field_presence.md +++ b/content/programming-guides/field_presence.md @@ -19,9 +19,10 @@ types (numeric, string, bytes, and enums) which are defined with the `optional` label have *explicit presence*, like proto2 (this feature is enabled by default as release 3.15). -**NOTE:** We recommend always adding the `optional` label for proto3 basic -types. This provides a smoother path to editions, which uses explicit presence -by default. +{{% alert title="Note" color="note" %}} We +recommend always adding the `optional` label for proto3 basic types. This +provides a smoother path to editions, which uses explicit presence by +default.{{% /alert %}} ### Presence Disciplines @@ -214,9 +215,10 @@ For a singular field with numeric, enum, or string type: - A generated `clear_foo` method must be used to clear (i.e., un-set) the value. -**Note:** `Has_` methods are not generated for implicit members in most cases. -The exception to this behavior is Dart, which generates `has_` methods with -proto3 proto schema files. +{{% alert title="Note" color="note" %}} +`Has_` methods are not generated for implicit members in most cases. The +exception to this behavior is Dart, which generates `has_` methods with proto3 +proto schema files.{{% /alert %}} ### Considerations for Merging diff --git a/content/programming-guides/proto2.md b/content/programming-guides/proto2.md index 55b76779a..d04996540 100644 --- a/content/programming-guides/proto2.md +++ b/content/programming-guides/proto2.md @@ -406,7 +406,7 @@ automatically generated class: Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. - int32 + int32_t int int int32 @@ -421,7 +421,7 @@ automatically generated class: Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. - int64 + int64_t long int/long[4] *int64 @@ -434,7 +434,7 @@ automatically generated class: uint32 Uses variable-length encoding. - uint32 + uint32_t int[2] int/long[4] *uint32 @@ -447,7 +447,7 @@ automatically generated class: uint64 Uses variable-length encoding. - uint64 + uint64_t long[2] int/long[4] *uint64 @@ -461,7 +461,7 @@ automatically generated class: sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. - int32 + int32_t int int int32 @@ -475,7 +475,7 @@ automatically generated class: sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. - int64 + int64_t long int/long[4] *int64 @@ -489,7 +489,7 @@ automatically generated class: fixed32 Always four bytes. More efficient than uint32 if values are often greater than 228. - uint32 + uint32_t int[2] int/long[4] *uint32 @@ -503,7 +503,7 @@ automatically generated class: fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 256. - uint64 + uint64_t long[2] int/long[4] *uint64 @@ -516,7 +516,7 @@ automatically generated class: sfixed32 Always four bytes. - int32 + int32_t int int *int32 @@ -529,7 +529,7 @@ automatically generated class: sfixed64 Always eight bytes. - int64 + int64_t long int/long[4] *int64 diff --git a/content/programming-guides/proto3.md b/content/programming-guides/proto3.md index cd9ce5ba4..b1d0b797b 100644 --- a/content/programming-guides/proto3.md +++ b/content/programming-guides/proto3.md @@ -410,7 +410,7 @@ automatically generated class: Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. - int32 + int32_t int int int32 @@ -425,7 +425,7 @@ automatically generated class: Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. - int64 + int64_t long int/long[4] int64 @@ -438,7 +438,7 @@ automatically generated class: uint32 Uses variable-length encoding. - uint32 + uint32_t int[2] int/long[4] uint32 @@ -451,7 +451,7 @@ automatically generated class: uint64 Uses variable-length encoding. - uint64 + uint64_t long[2] int/long[4] uint64 @@ -465,7 +465,7 @@ automatically generated class: sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. - int32 + int32_t int int int32 @@ -479,7 +479,7 @@ automatically generated class: sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. - int64 + int64_t long int/long[4] int64 @@ -493,7 +493,7 @@ automatically generated class: fixed32 Always four bytes. More efficient than uint32 if values are often greater than 228. - uint32 + uint32_t int[2] int/long[4] uint32 @@ -507,7 +507,7 @@ automatically generated class: fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 256. - uint64 + uint64_t long[2] int/long[4] uint64 @@ -520,7 +520,7 @@ automatically generated class: sfixed32 Always four bytes. - int32 + int32_t int int int32 @@ -533,7 +533,7 @@ automatically generated class: sfixed64 Always eight bytes. - int64 + int64_t long int/long[4] int64 diff --git a/content/reference/cpp/arenas.md b/content/reference/cpp/arenas.md index 1c8999bd7..08fda183d 100644 --- a/content/reference/cpp/arenas.md +++ b/content/reference/cpp/arenas.md @@ -57,16 +57,16 @@ messages in your file, as used in the following example. #include { google::protobuf::Arena arena; - MyMessage* message = google::protobuf::Arena::CreateMessage(&arena); + MyMessage* message = google::protobuf::Arena::Create(&arena); // ... } ``` -The message object created by `CreateMessage()` exists for as long as `arena` -exists, and you should not `delete` the returned message pointer. All of the -message object's internal storage (with a few exceptions[^1]) and submessages -(for example, submessages in a repeated field within `MyMessage`) are allocated -on the arena as well. +The message object created by `Create()` exists for as long as `arena` exists, +and you should not `delete` the returned message pointer. All of the message +object's internal storage (with a few exceptions[^1]) and submessages (for +example, submessages in a repeated field within `MyMessage`) are allocated on +the arena as well. For the most part, the rest of your code will be the same as if you weren't using arena allocation. @@ -98,40 +98,41 @@ class. This class implements the following public methods. ### Allocation Methods {#allocation} -- `template static T* CreateMessage(Arena* arena)`: Creates a new - protocol buffer object of message type `T` on the arena. - - If `arena` is not NULL, the returned message object is allocated on the - arena, its internal storage and submessages (if any) will be allocated on - the same arena, and its lifetime is the same as that of the arena. The - object must not be deleted/freed manually: the arena owns the message object - for lifetime purposes. - - If `arena` is NULL, the returned message object is allocated on the heap, - and the caller owns the object upon return. - -- `template static T* Create(Arena* arena, args...)`: Similar to - `CreateMessage()` but lets you create an object of any class on the arena, - not just protocol buffer message types. For example, let's say you have this - C++ class: - - ```cpp - class MyCustomClass { - MyCustomClass(int arg1, int arg2); - // ... - }; - ``` - - ...you can create an instance of it on the arena like this: - - ```cpp - void func() { - // ... - google::protobuf::Arena arena; - MyCustomClass* c = google::protobuf::Arena::Create(&arena, constructor_arg1, constructor_arg2); - // ... - } - ``` +* `template static T* Create(Arena* arena)` or `template static T* Create(Arena* arena, args...)` + + * If `T` is fully compatible[^footnote], then the method creates a new + protocol buffer object of type `T` and its subobjects on the arena. + + If `arena` is not NULL, the returned object is allocated on the arena, + its internal storage and sub-types (if any) will be allocated on the + same arena, and its lifetime is the same as that of the arena. The + object must not be deleted/freed manually: the arena owns the object for + lifetime purposes. + + If `arena` is NULL, the returned object is allocated on the heap, and + the caller owns the object upon return. + + * If `T` is a user-type, the method lets you create an object but not the + subobjects on the arena. For example, let's say you have this C++ class: + + ```cpp + class MyCustomClass { + MyCustomClass(int arg1, int arg2); + // ... + }; + ``` + + ...you can create an instance of it on the arena like this: + + ```cpp + void func() { + // ... + google::protobuf::Arena arena; + MyCustomClass* c = google::protobuf::Arena::Create(&arena, constructor_arg1, constructor_arg2); + // ... + } + ``` - `template static T* CreateArray(Arena* arena, size_t n)`: If `arena` is not NULL, this method allocates raw storage for `n` elements of @@ -142,6 +143,9 @@ class. This class implements the following public methods. `T` must have a trivial constructor: constructors are not called when the array is created on the arena. +[^footnote]: What it takes to be a "fully compatible" type is internal to the + protobuf library, and should not be assumed to be reliable. + ### "Owned list" Methods {#owned-list} The following methods let you specify that particular objects or destructors are @@ -220,8 +224,8 @@ allocation. use-after-free bugs. - `Message* New(Arena* arena)`: An alternate override for the standard `New()` method. It allows a new message object of this type to be created on the - given arena. Its semantics are identical to `Arena::CreateMessage(arena)` - if the concrete message type on which it is called is generated with arena + given arena. Its semantics are identical to `Arena::Create(arena)` if the + concrete message type on which it is called is generated with arena allocation enabled. If the message type is not generated with arena allocation enabled, then it is equivalent to an ordinary allocation followed by `arena->Own(message)` if `arena` is not NULL. @@ -459,11 +463,11 @@ Let's say you have created the following messages on an arena. ```cpp Arena* arena = new google::protobuf::Arena(); MyFeatureMessage* arena_message_1 = - google::protobuf::Arena::CreateMessage(arena); + google::protobuf::Arena::Create(arena); arena_message_1->mutable_nested_message()->set_feature_id(11); MyFeatureMessage* arena_message_2 = - google::protobuf::Arena::CreateMessage(arena); + google::protobuf::Arena::Create(arena); ``` The following code makes inefficient usage of the `release_...()` API: @@ -499,7 +503,7 @@ For example, the following code incurs a copy in the `Swap()` call: ```cpp MyFeatureMessage* message_1 = - google::protobuf::Arena::CreateMessage(arena); + google::protobuf::Arena::Create(arena); message_1->mutable_nested_message()->set_feature_id(11); MyFeatureMessage* message_2 = new MyFeatureMessage; @@ -513,7 +517,7 @@ To avoid the copy in this code, you allocate `message_2` on the same arena as ```cpp MyFeatureMessage* message_2 = - google::protobuf::Arena::CreateMessage(arena); + google::protobuf::Arena::Create(arena); ``` ### Granularity {#granularity} @@ -569,7 +573,7 @@ Message construction and deallocation: Arena arena; MyFeatureMessage* arena_message = - google::protobuf::Arena::CreateMessage(&arena); + google::protobuf::Arena::Create(&arena); arena_message->set_feature_name("Proto2 Arena"); arena_message->mutable_feature_data()->Add(2); diff --git a/content/reference/cpp/cpp-generated.md b/content/reference/cpp/cpp-generated.md index 3b4a1b6a7..8b9d58f1d 100644 --- a/content/reference/cpp/cpp-generated.md +++ b/content/reference/cpp/cpp-generated.md @@ -877,7 +877,9 @@ is a special container type used in protocol buffers to store map fields. As you can see from its interface below, it uses a commonly-used subset of `std::map` and `std::unordered_map` methods. -**NOTE:** These maps are unordered. +{{% alert title="Note" color="note" %}} These maps +are +unordered.{{% /alert %}} ```cpp template { diff --git a/content/reference/dart/dart-generated.md b/content/reference/dart/dart-generated.md index 9ca38c59c..b9c965a43 100644 --- a/content/reference/dart/dart-generated.md +++ b/content/reference/dart/dart-generated.md @@ -151,12 +151,15 @@ The compiler will generate the following accessor methods in the message class: - `void clearFoo()`: Clears the value of the field. After calling this,`get foo` will return the default value. -**NOTE:** Due to a quirk in the Dart proto3 implementation, the following -methods are generated even if the `optional` modifier, used to request -[presence semantics](/programming-guides/field_presence#presence-in-proto3-apis), -isn't in the proto definition. + {{% alert title="Note" color="note" %}} Due to a + quirk in the Dart proto3 implementation, the following methods are generated + even if the `optional` modifier, used to request + [presence semantics](/programming-guides/field_presence#presence-in-proto3-apis), + isn't in the proto + definition.{{% /alert %}} - `bool hasFoo()`: Returns `true` if the field is set. + - `void clearFoo()`: Clears the value of the field. After calling this, `hasFoo()` will return `false` and `get foo` will return the default value. diff --git a/content/reference/go/faq.md b/content/reference/go/faq.md index 7d8b27e1c..4cfe14fef 100644 --- a/content/reference/go/faq.md +++ b/content/reference/go/faq.md @@ -152,9 +152,11 @@ Common ways that namespace conflicts occur: deliberately chosen to be universally unique (for example, prefixed with the name of a company). - * **Warning:** Retroactively changing the package name on a `.proto` file - is not backwards compatible for types used as extension fields, stored - in `google.protobuf.Any`, or for gRPC Service definitions. +{{% alert title="Warning" color="warning" %}} +Retroactively changing the package name on a `.proto` file is not backwards +compatible for types used as extension fields, stored in `google.protobuf.Any`, +or for gRPC Service +definitions.{{% /alert %}} Starting with v1.26.0 of the `google.golang.org/protobuf` module, a hard error will be reported when a Go program starts up that has multiple conflicting diff --git a/content/reference/go/opaque-migration.md b/content/reference/go/opaque-migration.md index 7d0868422..72e58deb0 100644 --- a/content/reference/go/opaque-migration.md +++ b/content/reference/go/opaque-migration.md @@ -102,10 +102,12 @@ Protocol Buffers and Go Protobuf: go get google.golang.org/protobuf@latest ``` - **Note:** if you are not yet importing `google.golang.org/protobuf`, you - might still be on an older module. See + {{% alert title="Note" color="note" %}} If you + are not yet importing `google.golang.org/protobuf`, you might still be on an + older module. See [the `google.golang.org/protobuf` announcement (from 2020)](https://go.dev/blog/protobuf-apiv2) - and migrate your code before returning to this page. + and migrate your code before returning to this + page.{{% /alert %}} ### Step 1. Switch to the Hybrid API {#setup} diff --git a/content/reference/java/java-generated.md b/content/reference/java/java-generated.md index 25c745790..173cbb0fd 100644 --- a/content/reference/java/java-generated.md +++ b/content/reference/java/java-generated.md @@ -63,8 +63,10 @@ enum, or message (including nested types) in the file with the same name, `java_outer_classname` is also set to the string `FooService`, then the wrapper class will generate a class name of `FooServiceOuterClass`. -**Note:** If you are using the deprecated v1 of the protobuf API, `OuterClass` -is added regardless of any collisions with message names. +{{% alert title="Note" color="note" %}}If you are +using the deprecated v1 of the protobuf API, `OuterClass` is added regardless of +any collisions with message +names.{{% /alert %}} In addition to any nested classes, the wrapper class itself will have the following API (assuming the wrapper class is named `Foo` and was generated from @@ -111,6 +113,11 @@ provide an output location ending in `.jar`. Note that only the Java source code is placed in the archive; you must still compile it separately to produce Java class files. +## Packages {#package} + +The generated class is placed in a Java package based on the `java_package` +option. If the option is omitted, the `package` declaration is used instead. + For example, if the `.proto` file contains: ```proto diff --git a/content/reference/protobuf/proto3-spec.md b/content/reference/protobuf/proto3-spec.md index 3d161984c..166ff21ab 100644 --- a/content/reference/protobuf/proto3-spec.md +++ b/content/reference/protobuf/proto3-spec.md @@ -179,7 +179,7 @@ fieldNumber = intLit; Each field has type, name and field number. It may have field options. ``` -field = [ "repeated" ] type fieldName "=" fieldNumber [ "[" fieldOptions "]" ] ";" +field = [ "repeated" | "optional" ] type fieldName "=" fieldNumber [ "[" fieldOptions "]" ] ";" fieldOptions = fieldOption { "," fieldOption } fieldOption = optionName "=" constant ``` diff --git a/content/reference/rust/building-rust-protos.md b/content/reference/rust/building-rust-protos.md index 841282a27..56c8daf88 100644 --- a/content/reference/rust/building-rust-protos.md +++ b/content/reference/rust/building-rust-protos.md @@ -60,6 +60,7 @@ other programming languages: ) ``` -**Note:** Don't use `rust_upb_proto_library` or `rust_cc_proto_library` -directly. `rust_proto_library` checks the global build flag to choose the -appropriate backend for you. +{{% alert title="Note" color="note" %}} Don't use +`rust_upb_proto_library` or `rust_cc_proto_library` directly. +`rust_proto_library` checks the global build flag to choose the appropriate +backend for you. {{% /alert %}} diff --git a/content/support/version-support.md b/content/support/version-support.md index d6cbe098b..c0a2ecb80 100644 --- a/content/support/version-support.md +++ b/content/support/version-support.md @@ -374,13 +374,14 @@ Future plans are shown in *italics* and are subject to change. -**NOTE:** The maintenance support window for the Protobuf Java 3.x release will -be 24 months rather than the typical 12 months for the final release in a major +{{% alert title="Note" color="note" %}} +The maintenance support window for the Protobuf Java 3.x release will be 24 +months rather than the typical 12 months for the final release in a major version line. Future major version updates (5.x, planned for Q1 2026) will adopt an improved ["rolling compatibility window"](/support/cross-version-runtime-guarantee/#major) that should allow a return to 12-month support windows. There will be no major -version bump in Q1 2025. +version bump in Q1 2025.{{% /alert %}} **Release support chart**