Merge pull request protocolbuffers#251 from Logofile/sync

Documentation change

Author: Logofile

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;

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:

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

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}
 

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

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

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

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

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.
 

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}