From 697cbb285d690c94b779514230337814c954f853 Mon Sep 17 00:00:00 2001 From: Protocol Buffer Team Date: Wed, 10 Apr 2024 16:15:04 +0000 Subject: [PATCH 1/4] PiperOrigin-RevId: 623514390 Change-Id: I80fa75dc9fcd7bc3d51906653008979adbc0ec31 --- .github/workflows/gh-pages.yml | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 2de280a20..d66a08bdb 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -14,13 +14,17 @@ jobs: contents: write runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: submodules: true # Fetch Hugo themes (true OR recursive) fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod + - uses: actions/setup-node@v4 + with: + node-version: 20 + - name: Setup Hugo - uses: peaceiris/actions-hugo@v2 + uses: peaceiris/actions-hugo@v3 with: hugo-version: 0.121.2 extended: true @@ -32,7 +36,7 @@ jobs: run: hugo --minify - name: Deploy - uses: peaceiris/actions-gh-pages@v3 + uses: peaceiris/actions-gh-pages@v4 if: github.ref == 'refs/heads/main' with: github_token: ${{ secrets.GITHUB_TOKEN }} From 2f25cfda1fbacc7c2818b4c7dd82792208848d46 Mon Sep 17 00:00:00 2001 From: Protocol Buffer Team Date: Thu, 15 Aug 2024 20:16:42 +0000 Subject: [PATCH 2/4] This documentation change includes the following: * Pins the version for Hugo to prevent rendering issues * Corrects the protoc compiler command line in the Python tutorial * Adds additional information about enums and how they behave in editions * Adds information about how to get a Builder instance in Java * Corrects the names of methods for Ruby enums PiperOrigin-RevId: 663425236 Change-Id: Idb326bb419539b15e55cafec1d279bad8a7e45d1 --- .github/workflows/gh-pages.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index d66a08bdb..e92cdd8fc 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -21,11 +21,14 @@ jobs: - uses: actions/setup-node@v4 with: +<<<<<<< HEAD node-version: 20 - name: Setup Hugo uses: peaceiris/actions-hugo@v3 with: +======= +>>>>>>> fed30ed (This documentation change includes the following:) hugo-version: 0.121.2 extended: true From c18c8a72de22b99eaf536eb1f961371510159714 Mon Sep 17 00:00:00 2001 From: Protocol Buffer Team Date: Tue, 18 Mar 2025 14:22:39 +0000 Subject: [PATCH 3/4] This documentation change includes the following: * Adds an entry about `java_outer_classnames` to the best practices topic * Updates the version-tables.css file so that the version support topic shows the latest release. Also updates the version support topic for the V30 release. * Updates examples in the extensions declarations topic to use editions syntax * Adds an additional example to the style guide to clarify that a digit shouldn't follow an underscore even if that digit is followed by alphanumeric characters. Also updates link text in that topic to match the topic linked-to. * Adds information about embedded message fields with Java to the Java generated code topic * Adds information about repeated fields in Ruby to the Ruby generated code topic * Fixes anchor tag in the migration topic * Adds a section about the levels at which features can be set to `/content/editions/features.md`. Also adds notes throughout to point back to the new section PiperOrigin-RevId: 737995644 Change-Id: I278fe6c137970c7e4b0dc8532aad905d8ba9720a --- content/best-practices/dos-donts.md | 10 +++ content/best-practices/no-cargo-cults.md | 4 +- content/editions/_index.md | 2 +- content/editions/features.md | 80 ++++++++++++++++--- content/includes/version-tables.css | 14 ++-- .../extension_declarations.md | 4 +- content/programming-guides/json.md | 6 +- content/programming-guides/style.md | 4 +- content/reference/java/java-generated.md | 5 +- content/reference/ruby/ruby-generated.md | 16 ++++ content/support/migration.md | 2 +- content/support/version-support.md | 23 +++--- 12 files changed, 134 insertions(+), 36 deletions(-) diff --git a/content/best-practices/dos-donts.md b/content/best-practices/dos-donts.md index c89701585..ced1c2c0c 100644 --- a/content/best-practices/dos-donts.md +++ b/content/best-practices/dos-donts.md @@ -277,6 +277,16 @@ example, see You should also avoid using keywords in your file paths, as this can also cause problems. +## **Do** Use java_outer_classname {#java-outer-classname} + +Every proto schema definition file should set option `java_outer_classname` to +the `.proto` file name converted to TitleCase with the '.' removed. For example, +the file `student_record_request.proto` should set: + +```java +option java_outer_classname = "StudentRecordRequestProto"; +``` + ## Appendix {#appendix} ### API Best Practices {#api-best-practices} diff --git a/content/best-practices/no-cargo-cults.md b/content/best-practices/no-cargo-cults.md index 03d740b35..183cc15cc 100644 --- a/content/best-practices/no-cargo-cults.md +++ b/content/best-practices/no-cargo-cults.md @@ -5,7 +5,9 @@ description = "Avoid using features where they are not needed." type = "docs" +++ -Do not [cargo cult](http://go/cargocult-definition) settings in proto files. If +Do not +[cargo cult](https://en.wikipedia.org/wiki/Cargo_cult_programming) +settings in proto files. If \ you are creating a new proto file based on existing schema definitions, don't apply option settings except for those that you understand the need for. diff --git a/content/editions/_index.md b/content/editions/_index.md index 4f6348e68..6819f57da 100644 --- a/content/editions/_index.md +++ b/content/editions/_index.md @@ -5,6 +5,6 @@ description = "Topics related to the Protobuf Editions functionality." type = "docs" +++ -* [Protocol Buffers Overview](/editions/overview) +* [Protobuf Editions Overview](/editions/overview) * [Feature Settings for Editions](/editions/features) * [Implementing Editions Support](/editions/implementation) diff --git a/content/editions/features.md b/content/editions/features.md index 3f88f2687..748b0e020 100644 --- a/content/editions/features.md +++ b/content/editions/features.md @@ -29,18 +29,33 @@ act like proto2 or proto3 files. For more information on how Editions and Features work together to set behavior, see [Protobuf Editions Overview](/editions/overview). -Each of the following sections has an entry for what scope the feature applies -to. This can include file, enum, message, or field. The following sample shows a -mock feature applied to each scope: + Feature settings apply at different levels: + +**File-level:** These settings apply to all elements (messages, fields, enums, +and so on) that don't have an overriding setting. + +**Non-nested:** Messages, enums, and services can override settings made at the +file level. They apply to everything within them (message fields, enum values) +that aren't overridden, but don't apply to other parallel messages and enums. + +**Nested:** Oneofs, messages, and enums can override settings from the message +they're nested in. + +**Lowest-level:** Fields, extensions, enum values, extension ranges, and methods +are the lowest level at which you can override settings. + +Each of the following sections has a comment that states what scope the feature +can be applied to. The following sample shows a mock feature applied to each +scope: ```proto edition = "2023"; -// File-scope definition +// File-level scope definition option features.bar = BAZ; enum Foo { - // Enum-scope definition + // Enum (non-nested scope) definition option features.bar = QUX; A = 1; @@ -48,16 +63,23 @@ enum Foo { } message Corge { - // Message-scope definition + // Message (non-nested scope) definition option features.bar = QUUX; - // Field-scope definition + message Garply { + // Message (nested scope) definition + option features.bar = WALDO; + string id = 1; + } + + // Field (lowest-level scope) definition Foo A = 1 [features.bar = GRAULT]; } ``` -In this example, the setting `GRAULT` in the field-scope feature definition -overrides the message-scope QUUX setting. +In this example, the setting "`GRAULT"` in the lowest-level scope feature +definition overrides the non-nested-scope "`QUUX`" setting. And within the +Garply message, "`WALDO`" overrides "`QUUX`." ### `features.enum_type` {#enum_type} @@ -83,6 +105,9 @@ and after of a proto3 file. **Behavior in proto3:** `OPEN` +**Note:** Feature settings on different schema elements +[have different scopes](#cascading). + The following code sample shows a proto2 file: ```proto @@ -102,6 +127,7 @@ this: edition = "2023"; enum Foo { + // Setting the enum_type feature overrides the default OPEN enum option features.enum_type = CLOSED; A = 2; B = 4; @@ -129,7 +155,7 @@ whether a protobuf field has a value. **Applicable to the following scopes:** File, Field -**Default value in the Edition 2023:** `EXPLICIT` +**Default behavior in the Edition 2023:** `EXPLICIT` **Behavior in proto2:** `EXPLICIT` @@ -138,6 +164,9 @@ which case it behaves like `EXPLICIT`. See [Presence in Proto3 APIs](/programming-guides/field_presence#presence-in-proto3-apis) for more information. +**Note:** Feature settings on different schema elements +[have different scopes](#cascading). + The following code sample shows a proto2 file: ```proto @@ -156,6 +185,7 @@ After running Prototiller, the equivalent code might look like this: edition = "2023"; message Foo { + // Setting the field_presence feature retains the proto2 required behavior int32 x = 1 [features.field_presence = LEGACY_REQUIRED]; int32 y = 2; repeated int32 z = 3; @@ -178,10 +208,13 @@ After running Prototiller, the equivalent code might look like this: ```proto edition = "2023"; +// Setting the file-level field_presence feature matches the proto3 implicit default option features.field_presence = IMPLICIT; message Bar { int32 x = 1; + // Setting the field_presence here retains the explicit state that the proto3 + // field has because of the optional syntax int32 y = 2 [features.field_presence = EXPLICIT]; repeated int32 z = 3; } @@ -214,6 +247,9 @@ and after of a proto3 file. Editions behavior matches the behavior in proto3. **Behavior in proto3:** `ALLOW` +**Note:** Feature settings on different schema elements +[have different scopes](#cascading). + The following code sample shows a proto2 file: ```proto @@ -230,7 +266,7 @@ After running Prototiller, the equivalent code might look like this: ```proto edition = "2023"; -features.json_format = LEGACY_BEST_EFFORT; +option features.json_format = LEGACY_BEST_EFFORT; message Foo { string bar = 1; @@ -270,6 +306,9 @@ the following conditions are met: **Behavior in proto3:** `LENGTH_PREFIXED`. Proto3 doesn't support `DELIMITED`. +**Note:** Feature settings on different schema elements +[have different scopes](#cascading). + The following code sample shows a proto2 file: ```proto @@ -318,6 +357,9 @@ for `repeated` fields has been migrated to in Editions. **Behavior in proto3:** `PACKED` +**Note:** Feature settings on different schema elements +[have different scopes](#cascading). + The following code sample shows a proto2 file: ```proto @@ -389,6 +431,9 @@ and after of a proto3 file. **Behavior in proto3:** `VERIFY` +**Note:** Feature settings on different schema elements +[have different scopes](#cascading). + The following code sample shows a proto2 file: ```proto @@ -441,6 +486,9 @@ before and after of a proto3 file. **Behavior in proto3:** `false` +**Note:** Feature settings on different schema elements +[have different scopes](#cascading). + The following code sample shows a proto2 file: ```proto @@ -495,6 +543,9 @@ specified on a field, but not both. **Behavior in proto3:** `STRING` +**Note:** Feature settings on different schema elements +[have different scopes](#cascading). + The following code sample shows a proto2 file: ```proto @@ -568,6 +619,9 @@ before and after of a proto3 file. **Behavior in proto3:** `DEFAULT` +**Note:** Feature settings on different schema elements +[have different scopes](#cascading). + The following code sample shows a proto2 file: ```proto @@ -592,6 +646,7 @@ option features.utf8_validation = NONE; option features.(pb.java).utf8_validation = VERIFY; message MyMessage { string foo = 1; + string bar = 2; } ``` @@ -618,6 +673,9 @@ files. **Behavior in proto3:** `false` +**Note:** Feature settings on different schema elements +[have different scopes](#cascading). + ## Preserving proto2 or proto3 Behavior {#preserving} You may want to move to the editions format but not deal with updates to the way diff --git a/content/includes/version-tables.css b/content/includes/version-tables.css index c0fb516d3..d694c1c5b 100644 --- a/content/includes/version-tables.css +++ b/content/includes/version-tables.css @@ -95,36 +95,36 @@ table.version-chart td.active { /* latest release column */ /* * How to advance the selection of the latest release: - * Replace class 'y24q4' in the following selectors with 'y25q1' (the class + * Replace class 'y25q1' in the following selectors with 'y25q2' (the class * referring to the quarter of the next release). Please also update this * instruction as a courtesy to the next maintainer. */ /* visually replace 'yyQq' heading with string 'Latest' */ -table.version-chart th.y24q4 span { +table.version-chart th.y25q1 span { display: none; } -table.version-chart th.y24q4::after { +table.version-chart th.y25q1::after { content: "Latest" } /* draw a focus rectangle around the latest release column */ -table.version-chart th.y24q4 { +table.version-chart th.y25q1 { border-top: 2px solid #e06666 !important; border-left: 2px solid #e06666 !important; border-right: 2px solid #e06666 !important; } -table.version-chart td.y24q4 { +table.version-chart td.y25q1 { font-weight: bold; border-left: 2px solid #e06666 !important; border-right: 2px solid #e06666 !important; } -table.version-chart tr:last-child td.y24q4 { +table.version-chart tr:last-child td.y25q1 { border-bottom: 2px solid #e06666 !important; } /* future release columns */ -table.version-chart td:not(:has(~ .y24q4)):not(.y24q4) { +table.version-chart td:not(:has(~ .y25q1)):not(.y25q1) { font-style: italic; } diff --git a/content/programming-guides/extension_declarations.md b/content/programming-guides/extension_declarations.md index 3fc145b78..cca3d71e6 100644 --- a/content/programming-guides/extension_declarations.md +++ b/content/programming-guides/extension_declarations.md @@ -45,7 +45,7 @@ declarations in C++, you can declare the field type, field name, and cardinality containing the full extension definition: ```proto -syntax = "proto2"; +edition = "2023"; message Foo { extensions 4 to 1000 [ @@ -108,7 +108,7 @@ This `reserved` tag is separate from the reserved keyword for regular fields and **does not require breaking up the extension range**. ```proto {highlight="context:reserved"} -syntax = "proto2"; +edition = "2023"; message Foo { extensions 4 to 1000 [ diff --git a/content/programming-guides/json.md b/content/programming-guides/json.md index d09ca9439..f4695416b 100644 --- a/content/programming-guides/json.md +++ b/content/programming-guides/json.md @@ -21,7 +21,11 @@ topic. When parsing JSON-encoded data into a protocol buffer, if a value is missing or if its value is `null`, it will be interpreted as the corresponding -[default value](/programming-guides/editions#default). +[default value](/programming-guides/editions#default). Multiple values for +singular fields (using duplicate or equivalent JSON keys) are accepted and the +last value is retained, as with binary format parsing. Note that not all +protobuf JSON parser implementations are conformant, and some nonconformant +implementations may reject duplicate keys instead. When generating JSON-encoded output from a protocol buffer, if a protobuf field has the default value and if the field doesn't support field presence, it will diff --git a/content/programming-guides/style.md b/content/programming-guides/style.md index 74f6e4190..928246f04 100644 --- a/content/programming-guides/style.md +++ b/content/programming-guides/style.md @@ -79,7 +79,7 @@ later used in a language where names are transformed to TitleCase where they collide. When applied, this style rule means that you should use `XYZ2` or `XYZ_V2` -rather than `XYZ_2`. +rather than `XYZ_2` or `XYZ_2V`. ## Packages {#packages} @@ -198,7 +198,7 @@ For more service-related guidance, see and [Don't Include Primitive Types in a Top-level Request or Response Proto](/programming-guides/api#dont-include-primitive-types) in the API Best Practices topic, and -[Define Messages in Separate Files](/best-practices/dos-donts#separate-files) +[Define Message Types in Separate Files](/best-practices/dos-donts#separate-files) in Proto Best Practices. ## Things to Avoid {#avoid} diff --git a/content/reference/java/java-generated.md b/content/reference/java/java-generated.md index d7cfcd03f..ae8bd9958 100644 --- a/content/reference/java/java-generated.md +++ b/content/reference/java/java-generated.md @@ -348,7 +348,10 @@ class. For message types, `setFoo()` also accepts an instance of the message's builder type as the parameter. This is just a shortcut which is equivalent to calling -`.build()` on the builder and passing the result to the method. +`.build()` on the builder and passing the result to the method. Further +modifying the sub-builder passed to `setFoo` will **not** be reflected in the +message class's builder. The message class's builder "takes ownership" of the +sub-message. If the field is not set, `getFoo()` will return a Foo instance with none of its fields set (possibly the instance returned by `Foo.getDefaultInstance()`). diff --git a/content/reference/ruby/ruby-generated.md b/content/reference/ruby/ruby-generated.md index c708386d2..d4af5b57f 100644 --- a/content/reference/ruby/ruby-generated.md +++ b/content/reference/ruby/ruby-generated.md @@ -274,6 +274,22 @@ int_repeatedfield.clear raise unless int_repeatedfield.empty? ``` +For repeated fields that contain messages, the constructor for +`Google::Protobuf::RepeatedField` supports a variant with three arguments: +`:message`, the class of the submessage, and the values to set: + +```ruby +first_message = MySubMessage.new(:foo => 42) +second_message = MySubMessage.new(:foo => 79) + +repeated_field = Google::Protobuf::RepeatedField.new( + :message, + MySubMessage, + [first_message, second_message] +) +message.sub_message_repeated_field = repeated_field +``` + The `RepeatedField` type supports all of the same methods as a regular Ruby `Array`. You can convert it to a regular Ruby Array with `repeated_field.to_a`. diff --git a/content/support/migration.md b/content/support/migration.md index fa2fc7322..473931ce0 100644 --- a/content/support/migration.md +++ b/content/support/migration.md @@ -810,7 +810,7 @@ with Abseil and STL. Notably, we've replaced the `MapPair` class with an alias to `std::pair`. This should be transparent for most users, but if you were using the class directly you may need to update your code. -### New JSON Parser {:#json-parser} +### New JSON Parser {#json-parser} Source of changes: [PR #10729](https://github.com/protocolbuffers/protobuf/pull/10729) diff --git a/content/support/version-support.md b/content/support/version-support.md index f3ae4400c..014f32090 100644 --- a/content/support/version-support.md +++ b/content/support/version-support.md @@ -126,16 +126,21 @@ Future plans are shown in *italics* and are subject to change. 16 Feb 2023 31 Mar 2025 - + 5.x 13 Mar 2024 31 Mar 2026 - + 6.x - Q1 2025 + 4 Mar 2025 31 Mar 2027 + + 7.x + Q1 2026 + 31 Mar 2028 + **Release support chart** @@ -486,14 +491,14 @@ Future plans are shown in *italics* and are subject to change. Release date End of support - + 3.x 16 Feb 2023 31 Mar 2026 - + 4.x - Q1 2025 + 4 Mar 2025 TBD @@ -701,14 +706,14 @@ Future plans are shown in *italics* and are subject to change. 16 Feb 2023 31 Mar 2025 - + 5.x 13 Mar 2024 31 Mar 2026 - + 6.x - Q1 2025 + 4 Mar 2025 TBD From 837e6a68428d1c90131c4f06e6d648fcc60ae331 Mon Sep 17 00:00:00 2001 From: Protocol Buffers Docs Date: Tue, 18 Mar 2025 21:51:39 +0000 Subject: [PATCH 4/4] Reverts accidental changes to the GitHub Pages configuration file. --- .github/workflows/gh-pages.yml | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index e92cdd8fc..2de280a20 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -14,21 +14,14 @@ jobs: contents: write runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v3 with: submodules: true # Fetch Hugo themes (true OR recursive) fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod - - uses: actions/setup-node@v4 - with: -<<<<<<< HEAD - node-version: 20 - - name: Setup Hugo - uses: peaceiris/actions-hugo@v3 + uses: peaceiris/actions-hugo@v2 with: -======= ->>>>>>> fed30ed (This documentation change includes the following:) hugo-version: 0.121.2 extended: true @@ -39,7 +32,7 @@ jobs: run: hugo --minify - name: Deploy - uses: peaceiris/actions-gh-pages@v4 + uses: peaceiris/actions-gh-pages@v3 if: github.ref == 'refs/heads/main' with: github_token: ${{ secrets.GITHUB_TOKEN }}