Merge pull request #120 from Logofile/sync

Documentation updates

Author: Logofile

content/getting-started/javatutorial.md

@@ -350,7 +350,8 @@ Person john =
     .addPhones(
       Person.PhoneNumber.newBuilder()
         .setNumber("555-4321")
-        .setType(Person.PhoneType.PHONE_TYPE_HOME))
+        .setType(Person.PhoneType.PHONE_TYPE_HOME)
+        .build());
     .build();
 ```
 

content/news/2022-02-05.md

@@ -0,0 +1,26 @@
++++
+title = "Changes announced February 5, 2024"
+linkTitle = "February 5, 2024"
+toc_hide = "true"
+description = "Changes announced for Protocol Buffers on February 5, 2024."
+type = "docs"
++++
+
+This topic covers breaking changes in Java, C++, and Python in the 26.x line.
+
+## JSON Formatter Option Changes {#JSON}
+
+Starting in the 26.x line, the JSON formatter option to print default-valued
+fields is replaced with a fixed way to handle proto2 and proto3 `optional`
+fields consistently.
+
+*   Java: `includingDefaultValueFields()` is replaced with
+    `alwaysPrintFieldsWithNoPresence()`.
+*   C++: `always_print_default_values` is replaced with
+    `always_print_fields_with_no_presence=True`.
+*   Py: `including_default_value_fields=True` is replaced with
+    `always_print_fields_with_no_presence=True`.
+
+The new flag behaves identically to the old flag on proto3 messages, but no
+longer applies to proto2 `optional` fields. The old flags applied to proto2
+`optional` fields but not proto3 `optional` fields.

content/news/2024-01-31.md

@@ -0,0 +1,30 @@
++++
+title = "Changes announced January 31, 2024"
+linkTitle = "January 31, 2024"
+toc_hide = "true"
+description = "Changes announced for Protocol Buffers on January 31, 2024."
+type = "docs"
++++
+
+This topic covers breaking changes in Python in the 26.x line.
+
+## Python Breaking Changes
+
+### Removing `setup.py` and `setup.cfg` support from GitHub
+
+In the 26.x release, `setup.py` and `setup.cfg` will no longer be present in the
+`python/` directory of
+[the GitHub repository](https://github.com/protocolbuffers/protobuf/tree/main/python)
+or GitHub
+[release tarballs](https://github.com/protocolbuffers/protobuf/releases). This
+means it will no longer be possible to build a Python package directly from the
+GitHub repo or release tarball.
+
+The Python source packages published
+[on PyPI](https://pypi.org/project/protobuf/#files) *will* continue to have a
+`setup.py` in the top-level directory. This is the supported and recommended way
+of building Python binary packages, for users who do not want to use the binary
+packages that we distribute on PyPI.
+
+For more information, see
+[#15671](https://github.com/protocolbuffers/protobuf/pull/15671).

content/news/_index.md

@@ -9,6 +9,10 @@ no_list = "true"
 News topics provide information about past events and changes with Protocol
 Buffers, and plans for upcoming changes.
 
+*   [February 5, 2024](/news/2024-02-05) - Breaking
+    changes in Java, C++, and Python in the 26.x line.
+*   [January 31, 2024](/news/2024-01-31) - Breaking
+    changes in the 26.x line for Python
 *   [January 5, 2024](/news/2024-01-05) - Breaking
     changes in the 26.x line for Ruby and Python
 *   [December 27, 2023](/news/2023-12-27) - Breaking

content/programming-guides/field_presence.md

@@ -613,9 +613,9 @@ Is field presence tracked?
 
 Field type             | Tracked?
 ---------------------- | ------------------------
+*Other* singular field | if defined as `optional`
 Singular message field | yes
 Field in a oneof       | yes
-*Other* singular field | if defined as `optional`
 Repeated field & map   | no
 
 **Edition 2023:**

content/programming-guides/proto2.md

@@ -622,14 +622,16 @@ different languages, see
 
 Removing enum values is a breaking change for persisted protos. Instead of
 removing a value, mark the value with the `reserved` keyword to prevent the enum
-value from being code-generated:
+value from being code-generated, or keep the value but indicate that it will be
+removed later by using the `deprecated` field option:
 
 ```proto
 enum PhoneType {
   PHONE_TYPE_UNSPECIFIED = 0;
   PHONE_TYPE_MOBILE = 1;
   PHONE_TYPE_HOME = 2;
   PHONE_TYPE_WORK = 3 [deprecated=true];
+  reserved 4,5;
 }
 ```
 
@@ -1824,13 +1826,26 @@ value.
 
 A proto2 JSON implementation may provide the following options:
 
+*   **Always emit fields without presence**: Fields that don't support presence
+    and that have their default value are omitted by default in JSON output (for
+    example, an implicit presence integer with a 0 value, implicit presence
+    string fields that are empty strings, and empty repeated and map fields). An
+    implementation may provide an option to override this behavior and output
+    fields with their default values.
+
+    As of v25.x, the C++, Java, and Python implementations are nonconformant, as
+    this flag affects proto2 `optional` fields but not proto3 `optional` fields.
+    A fix is planned for a future release.
+
 *   **Ignore unknown fields**: Proto2 JSON parser should reject unknown fields
     by default but may provide an option to ignore unknown fields in parsing.
+
 *   **Use proto field name instead of lowerCamelCase name**: By default proto2
     JSON printer should convert the field name to lowerCamelCase and use that as
     the JSON name. An implementation may provide an option to use proto field
     name as the JSON name instead. Proto2 JSON parsers are required to accept
     both the converted lowerCamelCase name and the proto field name.
+
 *   **Emit enum values as integers instead of strings**: The name of an enum
     value is used by default in JSON output. An option may be provided to use
     the numeric value of the enum value instead.

content/programming-guides/proto3.md

@@ -1383,9 +1383,12 @@ value.
 
 A proto3 JSON implementation may provide the following options:
 
-*   **Emit fields with default values**: Fields with default values are omitted
-    by default in proto3 JSON output. An implementation may provide an option to
-    override this behavior and output fields with their default values.
+*   **Always emit fields without presence**: Fields that don't support presence
+    and that have their default value are omitted by default in JSON output (for
+    example, an implicit presence integer with a 0 value, implicit presence
+    string fields that are empty strings, and empty repeated and map fields). An
+    implementation may provide an option to override this behavior and output
+    fields with their default values.
 *   **Ignore unknown fields**: Proto3 JSON parser should reject unknown fields
     by default but may provide an option to ignore unknown fields in parsing.
 *   **Use proto field name instead of lowerCamelCase name**: By default proto3

content/reference/python/python-generated.md

@@ -534,8 +534,11 @@ foo.bars.add(i=3)
 foo.bars[0] = Bar(i=15)  # Raises an exception
 # WRONG!
 foo.bars[:] = [Bar(i=15), Bar(i=17)]  # Also raises an exception
-# RIGHT
+# WRONG!
+# AttributeError: Cannot delete field attribute
 del foo.bars
+# RIGHT
+del foo.bars[:]
 foo.bars.extend([Bar(i=15), Bar(i=17)])
 ```
 

content/support/version-support.md

@@ -10,9 +10,9 @@ type = "docs"
 
 Support windows for protoc and the various languages are covered in the tables
 later in this topic. Version numbers throughout this topic use
-[SemVer](https://semver.org) conventions; in the version "3.21.7," we
-say that "3" is the major version, "21" is the minor version, and "7" is the
-micro or patch number.
+[SemVer](https://semver.org) conventions; in the version "3.21.7," we say that
+"3" is the major version, "21" is the minor version, and "7" is the micro or
+patch number.
 
 Starting with the v20.x protoc release, we changed our versioning scheme to
 enable nimbler updates to language-specific parts of Protocol Buffers. In the
@@ -34,6 +34,11 @@ release updates quarterly, on a best-effort basis. Our support windows are
 defined by our
 [library breaking change policy](https://opensource.google/documentation/policies/library-breaking-change).
 
+Protobuf does *not* consider enforcement of its documented language, tooling,
+platform, and library support policies to be a breaking change. For example, a
+release may drop support for an EOL language version without bumping major
+versions.
+
 ## Support Duration {#duration}
 
 The most recent release is always supported. Support for earlier minor versions
@@ -373,6 +378,8 @@ This table graphically shows support durations.
 Protobuf is committed to following the platform and library support policy
 described in
 [.NET Support Policy](https://opensource.google/documentation/policies/dotnet-support).
+For specific versions supported, see
+[Foundational .NET Support Matrix](https://github.com/google/oss-policies-info/blob/main/foundational-dotnet-support-matrix.md).
 
 ## Java {#java}
 
@@ -570,6 +577,14 @@ Java will target making major version bumps annually in Q1 of each year.
   </tr>
 </table>
 
+### Java Platform and Library Support {#java-support}
+
+Protobuf is committed to following the platform and library support policy
+described in
+[Java Support Policy](https://cloud.google.com/java/docs/supported-java-versions).
+For specific versions supported, see
+[Foundational Java Support Matrix](https://github.com/google/oss-policies-info/blob/main/foundational-java-support-matrix.md).
+
 ## Objective-C {#objc}
 
 This table provides specific dates for support duration.