From 8d8904f3ea3ce761422b0dbe1f1c39b13aa76f92 Mon Sep 17 00:00:00 2001 From: Protocol Buffer Team Date: Wed, 23 Apr 2025 17:54:55 +0000 Subject: [PATCH] This documentation change includes the following: * Adds an option to the proto definition in the Python tutorial * Adds a missing link in the /news topic to an article released previously * Adds information about file path uniqueness requirements to the Editions topic * Rewords content in the Enum topic to reflect the passage of time * Adds a clarifying note to the C++ generated code guide about the behavior of deep copies * Adds a caveat to the Dart generated code guide about cross-language issues with implicit presence fields * Fixes some copy/paste errors in the Rust generated code guide PiperOrigin-RevId: 750651589 Change-Id: I829dc0009399f50bc49606db2ea70eb43f6d73ff --- content/getting-started/pythontutorial.md | 2 -- content/news/_index.md | 2 ++ content/programming-guides/editions.md | 14 +++++++++++++ content/programming-guides/enum.md | 24 +++++++++-------------- content/programming-guides/json.md | 10 +++++----- content/programming-guides/proto2.md | 14 +++++++++++++ content/programming-guides/proto3.md | 18 +++++++++++++++-- content/reference/cpp/cpp-generated.md | 9 +++++++++ content/reference/dart/dart-generated.md | 8 ++++++++ content/reference/rust/rust-generated.md | 4 ++-- 10 files changed, 79 insertions(+), 26 deletions(-) diff --git a/content/getting-started/pythontutorial.md b/content/getting-started/pythontutorial.md index 595e431ec..5db695cbe 100644 --- a/content/getting-started/pythontutorial.md +++ b/content/getting-started/pythontutorial.md @@ -80,8 +80,6 @@ edition = "2023"; package tutorial; -option features.field_presence = EXPLICIT; - message Person { string name = 1; int32 id = 2; diff --git a/content/news/_index.md b/content/news/_index.md index e7e69f686..73bbe19fa 100644 --- a/content/news/_index.md +++ b/content/news/_index.md @@ -20,6 +20,8 @@ New news topics will also be published to the The following news topics provide information in the reverse order in which it was released. +* [March 18, 2025](/news/2025-03-18) - Dropping support + for Ruby 3.0 * [January 23, 2025](/news/2025-01-23) - Poison Java gencode * [December 18, 2024](/news/2024-12-18) - Go Protobuf: diff --git a/content/programming-guides/editions.md b/content/programming-guides/editions.md index 441a700e0..95052ecf7 100644 --- a/content/programming-guides/editions.md +++ b/content/programming-guides/editions.md @@ -2022,6 +2022,20 @@ protoc --proto_path=IMPORT_PATH --cpp_out=DST_DIR --java_out=DST_DIR --python_ou Multiple import directories can be specified by passing the `--proto_path` option multiple times; they will be searched in order. `-I=_IMPORT_PATH_` can be used as a short form of `--proto_path`. + +**Note:** File paths relative to their `proto_path` must be globally unique in a +given binary. For example, if you have `proto/lib1/data.proto` and +`proto/lib2/data.proto`, those two files cannot be used together with +`-I=proto/lib1 -I=proto/lib2` because it would be ambiguous which file `import +"data.proto"` will mean. Instead `-Iproto/` should be used and the global names +will be `lib1/data.proto` and `lib2/data.proto`. + +If you are publishing a library and other users may use your messages directly, +you should include a unique library name in the path that they are expected to +be used under to avoid file name collisions. If you have multiple directories in +one project, it is best practice to prefer setting one `-I` to a top level +directory of the project. + * You can provide one or more *output directives*: * `--cpp_out` generates C++ code in `DST_DIR`. See the diff --git a/content/programming-guides/enum.md b/content/programming-guides/enum.md index dd491eb9c..bff84ada3 100644 --- a/content/programming-guides/enum.md +++ b/content/programming-guides/enum.md @@ -161,7 +161,7 @@ There are two options for moving to conformant behavior: > exception when passed `Enum.UNRECOGNIZED`, whereas `setNameValue` will accept > `2`. -### Kotlin {#java} +### Kotlin {#kotlin} All known Kotlin releases are out of conformance. When a `proto2` file imports an enum defined in a `proto3` file, Kotlin treats that field as a **closed** @@ -184,17 +184,11 @@ PHP is conformant. ### Python {#python} -After [4.22.0](https://pypi.org/project/protobuf/4.22.0/) which was released -~2023-02-16, Python is conformant. +Python is conformant in versions above 4.22.0 (released 2023 Q1). -In 4.21.x, Python is conformant by default, but setting -`PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python` will cause it to be out of -conformance. - -Before 4.21.0, Python is out of conformance. - -When a `proto2` file imports an enum defined in a `proto3` file, non-conformant -Python versions treat that field as a **closed** enum. +Older versions which are no longer supported are out of conformance. When a +`proto2` file imports an enum defined in a `proto3` file, non-conformant Python +versions treat that field as a **closed** enum. ### Ruby {#ruby} @@ -203,11 +197,11 @@ All known Ruby releases are out of conformance. Ruby treats all enums as ### Objective-C {#obj-c} -After 22.0, Objective-C is conformant. +Objective-C is conformant in versions above 3.22.0 (released 2023 Q1). -Prior to 22.0, Objective-C was out of conformance. When a `proto2` file imported -an enum defined in a `proto3` file, it would treat that field as a **closed** -enum. +Older versions which are no longer supported and are out of conformance. When a +`proto2` file imports an enum defined in a `proto3` file, non-conformant ObjC +versions treat that field as a **closed** enum. ### Swift {#swift} diff --git a/content/programming-guides/json.md b/content/programming-guides/json.md index a56fa6733..e171e6056 100644 --- a/content/programming-guides/json.md +++ b/content/programming-guides/json.md @@ -21,11 +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). 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. +[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/proto2.md b/content/programming-guides/proto2.md index 7e06faeb4..5c40e40f5 100644 --- a/content/programming-guides/proto2.md +++ b/content/programming-guides/proto2.md @@ -2359,6 +2359,20 @@ protoc --proto_path=IMPORT_PATH --cpp_out=DST_DIR --java_out=DST_DIR --python_ou Multiple import directories can be specified by passing the `--proto_path` option multiple times; they will be searched in order. `-I=_IMPORT_PATH_` can be used as a short form of `--proto_path`. + +**Note:** File paths relative to their `proto_path` must be globally unique in a +given binary. For example, if you have `proto/lib1/data.proto` and +`proto/lib2/data.proto`, those two files cannot be used together with +`-I=proto/lib1 -I=proto/lib2` because it would be ambiguous which file `import +"data.proto"` will mean. Instead `-Iproto/` should be used and the global names +will be `lib1/data.proto` and `lib2/data.proto`. + +If you are publishing a library and other users may use your messages directly, +you should include a unique library name in the path that they are expected to +be used under to avoid file name collisions. If you have multiple directories in +one project, it is best practice to prefer setting one `-I` to a top level +directory of the project. + * You can provide one or more *output directives*: * `--cpp_out` generates C++ code in `DST_DIR`. See the diff --git a/content/programming-guides/proto3.md b/content/programming-guides/proto3.md index eb723775c..79031d268 100644 --- a/content/programming-guides/proto3.md +++ b/content/programming-guides/proto3.md @@ -1700,8 +1700,22 @@ protoc --proto_path=IMPORT_PATH --cpp_out=DST_DIR --java_out=DST_DIR --python_ou * `IMPORT_PATH` specifies a directory in which to look for `.proto` files when resolving `import` directives. If omitted, the current directory is used. Multiple import directories can be specified by passing the `--proto_path` - option multiple times; they will be searched in order. `-I=_IMPORT_PATH_` - can be used as a short form of `--proto_path`. + option multiple times. `-I=_IMPORT_PATH_` can be used as a short form of + `--proto_path`. + +**Note:** File paths relative to their `proto_path` must be globally unique in a +given binary. For example, if you have `proto/lib1/data.proto` and +`proto/lib2/data.proto`, those two files cannot be used together with +`-I=proto/lib1 -I=proto/lib2` because it would be ambiguous which file `import +"data.proto"` will mean. Instead `-Iproto/` should be used and the global names +will be `lib1/data.proto` and `lib2/data.proto`. + +If you are publishing a library and other users may use your messages directly, +you should include a unique library name in the path that they are expected to +be used under to avoid file name collisions. If you have multiple directories in +one project, it is best practice to prefer setting one `-I` to a top level +directory of the project. + * You can provide one or more *output directives*: * `--cpp_out` generates C++ code in `DST_DIR`. See the diff --git a/content/reference/cpp/cpp-generated.md b/content/reference/cpp/cpp-generated.md index 20466ee13..9a416ff4e 100644 --- a/content/reference/cpp/cpp-generated.md +++ b/content/reference/cpp/cpp-generated.md @@ -127,6 +127,15 @@ In addition to these methods, the `Foo` class defines the following methods: `option optimize_for = LITE_RUNTIME` is specified in the `.proto` file, then the return type changes to `std::string*`. +**Note:** The copy constructor and assignment operator perform a deep copy of +the message data. This ensures that each message object owns and manages its own +copy of the data, preventing issues like double frees or use-after-free errors. +This behavior is consistent with standard C++ practice for objects that own +their data, such as `std::vector`. For developers coming from languages with +different copy semantics (such as JavaScript or TypeScript, where shallow copies +might be more common), it is important to note that modifications to a copied +message will not affect the original message, and vice-versa. + The class also defines the following static methods: - `static const Descriptor* descriptor()`: Returns the type's descriptor. This diff --git a/content/reference/dart/dart-generated.md b/content/reference/dart/dart-generated.md index b9c965a43..d2df98b23 100644 --- a/content/reference/dart/dart-generated.md +++ b/content/reference/dart/dart-generated.md @@ -160,6 +160,14 @@ The compiler will generate the following accessor methods in the message class: - `bool hasFoo()`: Returns `true` if the field is set. + {{% alert title="Note" color="note" %}} This + value cannot really be trusted if the proto was serialized in another + language that supports implicit presence (for example, Java). Even though + Dart tracks presence, other languages do not, and round-tripping a + zero-valued implicit presence field will make it "disappear" from Dart's + perspective. + {{% /alert %}} + - `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/rust/rust-generated.md b/content/reference/rust/rust-generated.md index 946dd9591..ef4529261 100644 --- a/content/reference/rust/rust-generated.md +++ b/content/reference/rust/rust-generated.md @@ -191,7 +191,7 @@ The compiler will generate the following accessor methods: value. For other numeric field types (including `bool`), `int32` is replaced with the -corresponding C++ type according to the +corresponding Rust type according to the [scalar value types table](/programming-guides/proto3#scalar). ### Implicit Presence Numeric Fields (proto3) {#implicit-presence-numeric} @@ -208,7 +208,7 @@ int32 foo = 1; calling this, `foo()` will return value. For other numeric field types (including `bool`), `int32` is replaced with the -corresponding C++ type according to the +corresponding Rust type according to the [scalar value types table](/programming-guides/proto3#scalar). ### Optional String/Bytes Fields (proto2 and proto3) {#optional-string-byte}