Merge pull request #110 from Logofile/sync

This update includes the following:

Author: Logofile

content/editions/features.md

@@ -507,8 +507,8 @@ option features.enum_type = CLOSED;
 option features.repeated_field_encoding = EXPANDED;
 option features.json_format = LEGACY_BEST_EFFORT;
 option features.utf8_validation = NONE;
-option features.(pb.cpp).legacy_enum_closed = true;
-option features.(pb.java).legacy_enum_closed = true;
+option features.(pb.cpp).legacy_closed_enum = true;
+option features.(pb.java).legacy_closed_enum = true;
 ```
 
 ### Proto3 Behavior {#proto3-behavior}
@@ -526,8 +526,8 @@ option features.enum_type = OPEN;
 // features in Editions syntax
 option features.json_format = ALLOW;
 option features.utf8_validation = VERIFY;
-option features.(pb.cpp).legacy_enum_closed = false;
-option features.(pb.java).legacy_enum_closed = false;
+option features.(pb.cpp).legacy_closed_enum = false;
+option features.(pb.java).legacy_closed_enum = false;
 ```
 
 ### Caveats and Exceptions {#caveats}

content/editions/overview.md

@@ -252,7 +252,7 @@ as it applies the file-level setting. The `Employment` `enum`, though, will be
 ### Prototiller {#prototiller}
 
 We provide both a migration guide and migration tooling that ease the migration
-to editions. The tool, called Prototiller, will enable you to:
+to and between editions. The tool, called Prototiller, will enable you to:
 
 *   convert proto2 and proto3 definition files to the new editions syntax, at
     scale

content/getting-started/gotutorial.md

@@ -113,13 +113,6 @@ message Person {
   int32 id = 2;  // Unique ID number for this person.
   string email = 3;
 
-  enum PhoneType {
-    PHONE_TYPE_UNSPECIFIED = 0;
-    PHONE_TYPE_MOBILE = 1;
-    PHONE_TYPE_HOME = 2;
-    PHONE_TYPE_WORK = 3;
-  }
-
   message PhoneNumber {
     string number = 1;
     PhoneType type = 2;
@@ -130,6 +123,13 @@ message Person {
   google.protobuf.Timestamp last_updated = 5;
 }
 
+enum PhoneType {
+  PHONE_TYPE_UNSPECIFIED = 0;
+  PHONE_TYPE_MOBILE = 1;
+  PHONE_TYPE_HOME = 2;
+  PHONE_TYPE_WORK = 3;
+}
+
 // Our address book file is just one of these.
 message AddressBook {
   repeated Person people = 1;

content/news/2023-12-05.md

@@ -0,0 +1,67 @@
++++
+title = "Changes announced on December 5, 2023"
+linkTitle = "December 5, 2023"
+toc_hide = "true"
+description = "Changes announced for Protocol Buffers on December 5, 2023."
+type = "docs"
++++
+
+## Java Breaking Changes
+
+In v26, we are planning a major version bump for Java per our
+[breaking changes policy](/news/2022-07-06) and
+[version support policy](/support/version-support#java).
+
+The following sections outline the set of breaking changes that we plan to
+include in the 26.0 release of protocol buffers. Note that plans can and do
+change. These are potential breaking changes to be aware of, but they may not
+happen in this particular release, or they may not happen at all.
+
+### Poison Pilling Gencode / Runtime Mismatches
+
+Per our
+[Cross-Version Runtime Guarantees](/support/cross-version-runtime-guarantee),
+Protobuf does not support mixing generated code and runtimes across major
+version boundaries, or mixing generated code from a newer version of protoc with
+older runtimes within a single major runtime version. We plan to introduce
+“poison pills” to detect and enforce these disallowed mismatches.
+
+This is not considered a breaking change since this simply adds enforcement of
+existing policies, but may require users to update their generated code.
+
+### Breaking Compatibility with Old Generated Code
+
+v26.x will break compatibility with generated code from older major versions.
+Users should regenerate old generated code to be from the same version.
+
+For example, `GeneratedMessageV3`, which was originally introduced for backwards
+compatibility with generated code from v2.x.x against v3.x.x runtime, will be
+renamed to `GeneratedMessage`. Runtimes will be updated to support
+[Editions](/editions/overview/), which will not be
+compatible with old generated code.
+
+This is in accordance with our existing
+[Cross-Version Runtime Guarantees](/support/cross-version-runtime-guarantee)
+and is a breaking change.
+
+### Removing Deprecated Methods/Variables
+
+v26.x will remove access to deprecated methods and variables. These will
+generally have already been marked `@Deprecated` in a previous release.
+
+This will remove access to the following non-exhaustive list:
+
+*   Descriptor syntax APIs, which should be replaced with corresponding feature
+    accessors (such as `FieldDescriptor.hasPresence()`,
+    `EnumDescriptor.isClosed()`)
+
+*   TextFormat print methods, which should be replaced by corresponding
+    `TextFormat.printer()` methods.
+
+*   PARSER variable, which should be replaced by the `parser()` method.
+
+*   Runtime methods for old v2.x.x gencode compatibility. This is no longer
+    supported, as per our
+    [Cross Version Runtime Guarantees](/support/cross-version-runtime-guarantee).
+
+More details will be available in the corresponding release notes.

content/news/2023-12-13.md

@@ -0,0 +1,81 @@
++++
+title = "Changes announced on December 13, 2023"
+linkTitle = "December 13, 2023"
+toc_hide = "true"
+description = "Changes announced for Protocol Buffers on December 13, 2023."
+type = "docs"
++++
+
+## C++ Breaking Changes
+
+In v26, we are planning a major version bump for C++ as per our
+[breaking changes policy](/news/2022-07-06) and
+[version support policy](/support/version-support#python-support).
+
+The following sections outline the set of breaking changes that we plan to
+include in the 26.0 release of protocol buffers. Note that plans can and do
+change. These are potential breaking changes to be aware of, but they may not
+happen in this particular release, or they may not happen at all.
+
+### Remove deprecated clear APIs on repeated fields
+
+The following deprecated methods are removed:
+
+*   `RepeatedPtrField::ReleaseCleared()`
+*   `RepeatedPtrField::ClearedCount()`
+*   `RepeatedPtrField::AddCleared()`
+
+### Remove C++ legacy syntax descriptor APIs
+
+With the release of [editions](/editions), syntax is no
+longer supported for business logic. Instead, use the various feature helpers
+defined in
+[`descriptor.h`](/reference/cpp/api-docs/google.protobuf.descriptor)
+to query more targeted behaviors, such as
+[`has_presence`](/reference/cpp/api-docs/google.protobuf.descriptor#FieldDescriptor.has_presence.details),
+to query features in C++.
+
+### Remove deprecated syntax accessor
+
+We plan to remove the deprecated syntax accessor, `FileDescriptor::Syntax`, in
+v26. We recommend using the getters from `FileDescriptor::edition` instead.
+
+### Remove deprecated SupportsUnknownEnumValues method
+
+The `SupportsUnknownEnumValues` method was
+[deprecated in March, 2023](https://github.com/protocolbuffers/protobuf/pull/12129).
+We plan to remove it in v26.
+
+### Remove std::string error collector overrides
+
+We are planning to remove the deprecated `std::string` methods in error
+collectors.
+
+## Python Breaking Changes
+
+In v26, we are planning a major version bump for Python as per our
+[breaking changes policy](/news/2022-07-06) and
+[version support policy](/support/version-support#python-support).
+
+### Timestamps are checked for validity
+
+In v26, the system will check if `Timestamp` values are valid. Seconds must be
+in the range [-62135596800, 253402300799] and nanos must be in range [0,
+999999999]. Values outside those ranges will raise an exception.
+
+### Remove deprecated syntax accessor
+
+We plan to remove the deprecated syntax accessor, `FileDescriptor.syntax`, in
+v26. We plan to add `FileDescriptor.edition` in its place.
+
+### UnknownFields support removal
+
+In v25
+[`message.UnknownFields()`](https://googleapis.dev/python/protobuf/latest/google/protobuf/message.html#google.protobuf.message.Message.UnknownFields)
+was deprecated in pure Python and C++ extensions. We plan to remove it v26. Use
+the new
+[`UnknownFieldSet(message)`](https://googleapis.dev/python/protobuf/latest/google/protobuf/unknown_fields.html)
+support in `unknown_fields.py` as a replacement.
+
+More details about all of these changes will be available in the corresponding
+release notes.

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.
 
+*   [December 13, 2023](/news/2023-12-13) - Breaking
+    Python and C++ changes in the 26.x line
+*   [December 5, 2023](/news/2023-12-05) - Breaking Java
+    changes in the 26.x line
 *   [October 10, 2023](/news/2023-10-10) - Documentation
     for Protobuf Editions features is published
 *   [September 15, 2023](/news/2023-09-15) - μpb Moving

content/programming-guides/dos-donts.md

@@ -60,6 +60,8 @@ and whether someone will be forced to fill in your required field with an empty
 string or zero in four years when it’s no longer logically required but the
 proto still says it is.
 
+For proto3 there are no `required` fields, so this advice does not apply.
+
 <a id="dont-make-a-message-with-lots-of-fields"></a>
 
 ## **Don't** Make a Message with Lots of Fields {#lots-of-fields}

content/programming-guides/field_presence.md

@@ -37,7 +37,7 @@ the serialization contains no information about not-present values.
 The generated API for a proto message includes (de)serialization definitions
 which translate between API types and a stream of definitionally *present* (tag,
 value) pairs. This translation is designed to be forward- and
-backward-compatibile across changes to the message definition; however, this
+backward-compatible across changes to the message definition; however, this
 compatibility introduces some (perhaps surprising) considerations when
 deserializing wire-formatted messages:
 
@@ -566,7 +566,7 @@ if (m.hasFoo()) {
 }
 ```
 
-#### Objective C Example
+#### Objective-C Example
 
 No presence:
 
@@ -593,3 +593,38 @@ if (m.hasFoo()) {
   [m setFoo:1];
 }
 ```
+
+## Cheat sheet {#cheat}
+
+**Proto2:**
+
+Is field presence tracked?
+
+Field type             | Tracked?
+---------------------- | --------
+Singular field         | yes
+Singular message field | yes
+Field in a oneof       | yes
+Repeated field & map   | no
+
+**Proto3:**
+
+Is field presence tracked?
+
+Field type             | Tracked?
+---------------------- | ------------------------
+Singular message field | yes
+Field in a oneof       | yes
+*Other* singular field | if defined as `optional`
+Repeated field & map   | no
+
+**Edition 2023:**
+
+Is field presence tracked?
+
+Field type                                         | Tracked?
+-------------------------------------------------- | --------
+Default                                            | yes
+`features.field_presence` set to `LEGACY_REQUIRED` | yes
+`features.field_presence` set to `IMPLICIT`        | no
+Repeated field & map                               | no

content/programming-guides/proto2.md

@@ -620,6 +620,19 @@ different languages, see
 [Enum Behavior](/programming-guides/enum).
 {{% /alert %}}
 
+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:
+
+```proto
+enum PhoneType {
+  PHONE_TYPE_UNSPECIFIED = 0;
+  PHONE_TYPE_MOBILE = 1;
+  PHONE_TYPE_HOME = 2;
+  PHONE_TYPE_WORK = 3 [deprecated=true];
+}
+```
+
 For more information about how to work with message `enum`s in your
 applications, see the [generated code guide](/reference/)
 for your chosen language.

content/programming-guides/style.md

@@ -98,7 +98,9 @@ enum FooBar {
 ```
 
 Each enum value should end with a semicolon, not a comma. Prefer prefixing enum
-values instead of surrounding them in an enclosing message.
+values instead of surrounding them in an enclosing message. Since some languages
+don't support an enum being defined inside a "struct" type, this ensures a
+consistent approach across binding languages.
 
 The zero value enum should have the suffix `UNSPECIFIED`, because a server or
 application that gets an unexpected enum value will mark the field as unset in