Merge pull request #189 from Logofile/sync

Documentation changes

Author: Logofile

content/news/2024-10-02.md

@@ -157,6 +157,16 @@ and
 **Replacement:** `message_factory.GetMessageClass()` and
 `message_factory.GetMessageClassesForFiles()`.
 
+#### GetDebugString
+
+**APIs:**
+[`GetDebugString`](https://github.com/protocolbuffers/protobuf/blob/7f395af40e86e00b892e812beb67a03564884756/python/google/protobuf/pyext/descriptor.cc#L1510)
+
+**Replacement:**
+
+No replacement. It's only in Python C++ which is no longer released. It is not
+supported in pure Python or UPB.
+
 ## Changes in Objective-C {#objc}
 
 **This will be the first breaking release for Objective-C**.
@@ -263,6 +273,37 @@ which includes any unknown fields.
 and
 [-[`GPBMessage clearUnknownFields`]](https://github.com/protocolbuffers/protobuf/blob/224573d66a0cc958c76cb43d8b2eb3aa7cdb89f2/objectivec/GPBMessage.h#L497-L504C9)
 
+### Remove Deprecated Runtime APIs for Old Gencode {#objc-remove-apis-gencode}
+
+This release will remove deprecated runtime methods that support the Objective-C
+gencode from before the 3.22.x release. The library will also issue a log
+message at runtime when old generated code is starting up.
+
+**API:** [`+[GPBFileDescriptor
+allocDescriptorForClass:file:fields:fieldCount:storageSize:flags:]`](https://github.com/protocolbuffers/protobuf/blob/1b44ce0feef45a78ba99d09bd2e5ff5052a6541b/objectivec/GPBDescriptor_PackagePrivate.h#L213-L220)
+
+**Replacement:** Regenerate with a current version of the library.
+
+**API:** [`+[GPBFileDescriptor
+allocDescriptorForClass:rootClass:file:fields:fieldCount:storageSize:flags:]`](https://github.com/protocolbuffers/protobuf/blob/1b44ce0feef45a78ba99d09bd2e5ff5052a6541b/objectivec/GPBDescriptor_PackagePrivate.h#L221-L229)
+
+**Replacement:** Regenerate with a current version of the library.
+
+**API:** [`+[GPBEnumDescriptor
+allocDescriptorForName:valueNames:values:count:enumVerifier:]`](https://github.com/protocolbuffers/protobuf/blob/1b44ce0feef45a78ba99d09bd2e5ff5052a6541b/objectivec/GPBDescriptor_PackagePrivate.h#L285-L291)
+
+**Replacement:** Regenerate with a current version of the library.
+
+**API:** [`+[GPBEnumDescriptor
+allocDescriptorForName:valueNames:values:count:enumVerifier:extraTextFormatInfo:]`](https://github.com/protocolbuffers/protobuf/blob/1b44ce0feef45a78ba99d09bd2e5ff5052a6541b/objectivec/GPBDescriptor_PackagePrivate.h#L292-L299)
+
+**Replacement:** Regenerate with a current version of the library.
+
+**API:**
+[`-[GPBExtensionDescriptor initWithExtensionDescription:]`](https://github.com/protocolbuffers/protobuf/blob/1b44ce0feef45a78ba99d09bd2e5ff5052a6541b/objectivec/GPBDescriptor_PackagePrivate.h#L317-L320)
+
+**Replacement:** Regenerate with a current version of the library.
+
 ## Other Changes {#non-breaking}
 
 In addition to those breaking changes are some other changes worth noting. While

content/programming-guides/1-1-1.md

@@ -1,22 +1,34 @@
 +++
-title = "1-1-1 Rule"
+title = "1-1-1 Best Practice"
 weight = 105
-linkTitle = "1-1-1 Rule"
+linkTitle = "1-1-1 Best Practice"
 description = "All proto definitions should have one top-level element and build target per file."
 type = "docs"
 +++
 
-The 1-1-1 rule has the following elements:
+The 1-1-1 best practice is to keep every proto_library and .proto file as small
+as is reasonable, with the ideal being:
 
-*   One `proto_library` rule
+*   One `proto_library` build rule
 *   One source `.proto` file
 *   One top-level entity (message, enum, or extension)
 
-When defining a proto schema, you should have a single message, enum, extension,
-service, or group of cyclic dependencies per file. This makes refactoring
-easier. Moving files when they're separated is much easier than extracting
-messages from a file with other messages. Following this practice also helps to
-keep the proto schema files smaller, which enhances maintainability.
+Having the fewest number of message, enum, extension, and services as you
+reasonably can makes refactoring easier. Moving files when they're separated is
+much easier than extracting messages from a file with other messages.
+
+Following this practice can help build times and binary size by reducing the
+size of your transitive dependencies in practice: when some code only needs to
+use one enum, under a 1-1-1 design it can depend just on the .proto file that
+defines that enum and avoid incidentally pulling in a large set of transitive
+dependencies that may only be used by another message defined in the same file.
+
+There are cases where the 1-1-1 ideal is not possible (circular dependencies),
+not ideal (extremely conceptually coupled messages which have readability
+benefits by being co-located), or where the some of the downsides don't apply
+(when a .proto file has no imports, then there are no technical concerns about
+the size of transitive dependencies). As with any best practice, use good
+judgment for when to diverge from the guideline.
 
 One place that modularity of proto schema files is important is when creating
 gRPC