This change includes the following:

* Correct a code sample in the Java tutorial
* Adds a News entry about breaking changes in v26.x for Python
* Reorders content in a table about field presence tracking in Proto3
* In the proto2 language guide:
  * Updates the Enumerations section to give more information about deprecating and reserving values
  * Adds information about emitting fields without field presence tracking in JSON
* In the proto3 language guide, adds information about emitting fields without field presence tracking in JSON
* In the Python generated code topic, adds another example in the example code for repeated message fields
* Updates the version support topic:
  * Adds information about dropping support for deprecated languages not being a breaking change
  * Adds a link to C# versions supported
  * Adds a section about Java platform and language support

PiperOrigin-RevId: 603638025
Change-Id: I85a13a0f2765aded1bbb04dcaf6b48b2c050df02

Author: Protocol Buffer Team

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/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,8 @@ no_list = "true"
 News topics provide information about past events and changes with Protocol
 Buffers, and plans for upcoming changes.
 
+*   [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.