Merge pull request protocolbuffers#225 from Logofile/sync

Documentation update

Author: Logofile

content/best-practices/1-1-1.md

@@ -42,7 +42,7 @@ edition = "2023";
 
 package my.package;
 
-message StudentID {
+message StudentId {
   string value = 1;
 }
 ```
@@ -114,7 +114,7 @@ package my.package;
 import "student_id.proto";
 
 message GetStudentRequest {
-  StudentID id = 1;
+  StudentId id = 1;
 }
 ```
 
@@ -154,17 +154,17 @@ The service definition and each of the message definitions are each in their own
 file, and you use includes to give access to the messages from other schema
 files.
 
-In this example, `Student`, `StudentID`, and `FullName` are domain types that
+In this example, `Student`, `StudentId`, and `FullName` are domain types that
 are reusable across requests and responses. The top-level request and response
 protos are unique to each service+method.
 
 If you later need to add a `middle_name` field to the `FullName` message, you
 won't need to update every individual top-level message with that new field.
 Likewise, if you need to update `Student` with more information, all the
-requests and responses get the update. Further, `StudentID` might update to be a
+requests and responses get the update. Further, `StudentId` might update to be a
 multi-part ID.
 
-Lastly, having even simple types like `StudentID` wrapped as a message means
+Lastly, having even simple types like `StudentId` wrapped as a message means
 that you have created a type that has semantics and consolidated documentation.
 For something like `FullName` you'll need to be careful with where this PII gets
 logged; this is another advantage of not repeating these fields in multiple

content/editions/features.md

@@ -590,6 +590,29 @@ message MyMessage {
 }
 ```
 
+#### `features.(pb.java).large_enum` {#java-large_enum}
+
+**Languages:** Java
+
+This language-specific feature enables you to adopt new functionality that
+handles large enums in Java without causing compiler errors.
+
+This is new behavior, so doesn't affect proto2 or proto3 schema definition
+files.
+
+**Values available:**
+
+*   `true`: Java enums will use the new functionality.
+*   `false`: Java enums will continue to use Java enums.
+
+**Applicable to the following scopes:** Enum
+
+**Default behavior in Edition 2023:** `false`
+
+**Behavior in proto2:** `false`
+
+**Behavior in proto3:** `false`
+
 ## Preserving proto2 or proto3 Behavior {#preserving}
 
 You may want to move to the editions format but not deal with updates to the way

content/editions/overview.md

@@ -271,11 +271,9 @@ as it applies the file-level setting. The `Employment` `enum`, though, will be
 
 ### Prototiller {#prototiller}
 
-Currently, all conversions to editions format are handled by the Protobuf team.
-
-When this shifts to a self-serve model, we will provide both a migration guide
-and migration tooling to ease the migration to and between editions. The tool,
-called Prototiller, will enable you to:
+When the Prototiller tool is launched, we will
+provide both a migration guide and migration tooling to ease the migration to
+and between editions. The tool will enable you to:
 
 *   convert proto2 and proto3 definition files to the new editions syntax, at
     scale

content/news/2024-12-04.md

@@ -6,7 +6,7 @@ description = "Changes announced for Protocol Buffers on December 4, 2024."
 type = "docs"
 +++
 
-We are planning to modify the Protobuf debug APIs (including Protobuf
+We are planning to modify the Protobuf debug APIs for C++ (including Protobuf
 AbslStringify, `proto2::ShortFormat`, `proto2::Utf8Format`,
 `Message::DebugString`, `Message::ShortDebugString`, `Message::Utf8DebugString`)
 in v30 to redact sensitive fields annotated by `debug_redact`; the outputs of

content/news/2025-01-23.md

@@ -0,0 +1,38 @@
++++
+title = "Changes announced January 23, 2025"
+linkTitle = "January 23, 2025"
+toc_hide = "true"
+description = "Changes announced for Protocol Buffers on January 23, 2025."
+type = "docs"
++++
+
+## Poison Java gencode
+
+We are patching a change into the 25.x branch that will poison Java gencode that
+was created prior to the
+[3.21.7 release](https://github.com/protocolbuffers/protobuf/releases/tag/v21.7).
+We will then mark all versions of Java protobuf from 3.21.7 through 3.25.5 as
+vulnerable to the
+[footmitten CVE](https://github.com/protocolbuffers/protobuf/security/advisories/GHSA-h4h5-3hr4-j3g2).
+
+After this change is patched in, protobuf will throw an
+`UnsupportedOperationException` from the
+[`makeExtensionsImmutable`](https://protobuf.dev/reference/java/api-docs/com/google/protobuf/GeneratedMessage.html#makeExtensionsImmutable\(\))
+method unless you set the system property
+"`-Dcom.google.protobuf.use_unsafe_pre22_gencode`". Using this system property
+can buy you some time if you can't update your code immediately, but should be
+considered a short-term workaround.
+
+## Poison MSVC + Bazel
+
+We will be dropping support for using Bazel and MSVC together in v34. As of v30,
+we will poison this combination with an error unless you specify the opt-out
+flag `--define=protobuf_allow_msvc=true` to silence it.
+
+MSVC's path length limits combined with Bazel's sandboxing have become
+increasingly difficult to support in combination. Rather than randomly break
+users who install protobuf into a long path, we will prohibit the use of MSVC
+from Bazel altogether. We will continue to support MSVC with CMake, and begin
+supporting [clang-cl](https://clang.llvm.org/docs/UsersManual.html#clang-cl)
+with Bazel. For any feedback or discussion, see
+https://github.com/protocolbuffers/protobuf/issues/20085.

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.
 
+*   [January 23, 2025](/news/2025-01-23) - Poison Java
+    gencode
 *   [December 18, 2024](/news/2024-12-18) - Go Protobuf:
     The new Opaque API
 *   [December 13, 2024](/news/2024-12-13) - Removing

content/news/v25.md

@@ -45,3 +45,20 @@ same to minimize the need for additional changes, but there are two exceptions:
 -   The top-level `BUILD` file for μpb has moved into the `upb` directory. So,
     for example, references to `@upb//:reflection` should now be written
     `@com_google_protobuf//upb:reflection`.
+
+## Poison Java gencode
+
+We are patching a change into the 25.x branch that will poison Java gencode that
+was created prior to the
+[3.21.7 release](https://github.com/protocolbuffers/protobuf/releases/tag/v21.7).
+We will then mark all versions of Java protobuf from 3.21.7 through 3.25.5 as
+vulnerable to the
+[footmitten CVE](https://github.com/protocolbuffers/protobuf/security/advisories/GHSA-h4h5-3hr4-j3g2).
+
+After this change is patched in, protobuf will throw an
+`UnsupportedOperationException` from the
+[`makeExtensionsImmutable`](https://protobuf.dev/reference/java/api-docs/com/google/protobuf/GeneratedMessage.html#makeExtensionsImmutable\(\))
+method unless you set the system property
+"`-Dcom.google.protobuf.use_unsafe_pre22_gencode`". Using this system property
+can buy you some time if you can't update your code immediately, but should be
+considered a short-term workaround.

content/news/v30.md

@@ -111,7 +111,7 @@ This release will drop C++ 14 as the minimum supported version and raise it to
 Per [our policies](https://protobuf.dev/support/version-support), we do not
 consider this to be a breaking change.
 
-## Introduce ASAN Poisoning After Clearing Oneof Messages on Arena
+### Introduce ASAN Poisoning After Clearing Oneof Messages on Arena
 
 This change adds a hardening check that affects C++ protobufs using Arenas.
 Oneof messages allocated on the protobuf arena will now be cleared in debug and
@@ -120,7 +120,7 @@ region will cause a crash in ASAN as a use-after-free error.
 
 This implementation requires C++17.
 
-## Dropping our C++ CocoaPods release
+### Dropping our C++ CocoaPods release
 
 In v30, we will be dropping our C++ CocoaPods release, which has been broken
 since v4.x.x. C++ users should use our
@@ -381,7 +381,23 @@ allocDescriptorForName:valueNames:values:count:enumVerifier:extraTextFormatInfo:
 
 **Replacement:** Regenerate with a current version of the library.
 
-## Other Changes {#non-breaking}
+## Other Changes {#other}
+
+### Poison MSVC + Bazel
+
+We will be dropping support for using Bazel and MSVC together in v34. As of v30,
+we will poison this combination with an error unless you specify the opt-out
+flag `--define=protobuf_allow_msvc=true` to silence it.
+
+MSVC's path length limits combined with Bazel's sandboxing have become
+increasingly difficult to support in combination. Rather than randomly break
+users who install protobuf into a long path, we will prohibit the use of MSVC
+from Bazel altogether. We will continue to support MSVC with CMake, and begin
+supporting [clang-cl](https://clang.llvm.org/docs/UsersManual.html#clang-cl)
+with Bazel. For any feedback or discussion, see
+https://github.com/protocolbuffers/protobuf/issues/20085.
+
+## Other Changes (Non-Breaking) {#non-breaking}
 
 In addition to those breaking changes are some other changes worth noting. While
 the following are not considered breaking changes, they may still impact users.
@@ -399,7 +415,7 @@ v30 will includes a fix to make UTF-8 enforcement consistent across languages.
 Users with bad non-UTF8 data in string fields may see surfaced UTF-8 enforcement
 errors earlier.
 
-## Ruby and PHP Errors in JSON Parsing
+### Ruby and PHP Errors in JSON Parsing
 
 v30 fixes non-conformance in JSON parsing of strings in numeric fields per the
 [JSON spec](https://protobuf.dev/programming-guides/json/).

content/overview.md

@@ -233,9 +233,7 @@ std::string email = john.email();
 When defining `.proto` files, you can specify that a field is either `optional`
 or `repeated` (proto2 and proto3) or leave it set to the default, implicit
 presence, in proto3. (The option to set a field to `required` is absent in
-proto3 and strongly discouraged in proto2. For more on this, see "Required is
-Forever" in
-[Specifying Field Rules](/programming-guides/proto3#specifying-field-rules).)
+proto3 and strongly discouraged in proto2. For more on this, see [Required Fields Considered Harmful](/programming-guides/required-considered-harmful.md).)
 
 After setting the optionality/repeatability of a field, you specify the data
 type. Protocol buffers support the usual primitive data types, such as integers,

content/programming-guides/deserialize-debug.md

@@ -23,7 +23,7 @@ and a randomized-length whitespace sequence. The new debugging format looks as
 follows:
 
 ```none
-go/nodeserialize
+goo.gle/nodeserialize
 spii_field: [REDACTED]
 normal_field: "value"
 ```