diff --git a/content/reference/java/java-generated.md b/content/reference/java/java-generated.md index 173cbb0fd..d7cfcd03f 100644 --- a/content/reference/java/java-generated.md +++ b/content/reference/java/java-generated.md @@ -587,23 +587,24 @@ The values of this enum type have the following special methods: The compiler will generate the following accessor methods in both the message class and its builder: -- `boolean hasFooInt()`: Returns `true` if the oneof case is `FOO`. +- `boolean hasFooInt()`: Returns `true` if the oneof case is `FOO_INT`. - `int getFooInt()`: Returns the current value of `foo` if the oneof case is - `FOO`. Otherwise, returns the default value of this field. + `FOO_INT`. Otherwise, returns the default value of this field. - `ChoiceCase getChoiceCase()`: Returns the enum indicating which field is set. Returns `CHOICE_NOT_SET` if none of them is set. The compiler will generate the following methods only in the message's builder: - `Builder setFooInt(int value)`: Sets `Foo` to this value and sets the oneof - case to `FOO`. After calling this, `hasFooInt()` will return `true`, - `getFooInt()` will return `value` and `getChoiceCase()` will return `FOO`. + case to `FOO_INT`. After calling this, `hasFooInt()` will return `true`, + `getFooInt()` will return `value` and `getChoiceCase()` will return + `FOO_INT`. - `Builder clearFooInt()`: - - Nothing will be changed if the oneof case is not `FOO`. - - If the oneof case is `FOO`, sets `Foo` to null and the oneof case to - `FOO_NOT_SET`. After calling this, `hasFooInt()` will return `false`, + - Nothing will be changed if the oneof case is not `FOO_INT`. + - If the oneof case is `FOO_INT`, sets `Foo` to null and the oneof case to + `CHOICE_NOT_SET`. After calling this, `hasFooInt()` will return `false`, `getFooInt()` will return the default value and `getChoiceCase()` will - return `FOO_NOT_SET`. + return `CHOICE_NOT_SET`. - `Builder.clearChoice()`: Resets the value for `choice`, returning the builder. diff --git a/content/support/migration.md b/content/support/migration.md index 53468a84a..fa2fc7322 100644 --- a/content/support/migration.md +++ b/content/support/migration.md @@ -6,6 +6,577 @@ aliases = "/programming-guides/migration/" type = "docs" +++ +## Changes in v30.0 {#v30} + +The following is a list of the breaking changes made to versions of the +libraries, and how to update your code to accommodate the changes. + +This covers breaking changes announced in +[News Announcements for v30.x](/news/v30) and +[Release Notes for v30.0](https://github.com/protocolbuffers/protobuf/releases/tag/v30.0). + +### Replaced CMake Submodules with Fetched Deps + +Previously, our default CMake behavior was to use Git submodules to grab pinned +dependencies. Specifying `-Dprotobuf_ABSL_PROVIDER=package` would flip our CMake +configs to look for local installations of Abseil (with similar options for +jsoncpp and gtest). These options no longer exist, and the default behavior is +to first look for installations of all our dependencies, falling back to +fetching pinned versions from GitHub if needed. + +To prevent any fallback fetching (similar to the old `package` behavior), you +can call CMake with: + +```cmake +cmake . -Dprotobuf_LOCAL_DEPENDENCIES_ONLY=ON +``` + +To *always* fetch dependencies from a fixed version (similar to the old default +behavior), you can call CMake with: + +```cmake +cmake . -Dprotobuf_FORCE_FETCH_DEPENDENCIES=ON +``` + +### string_view return type + +Return types are now `absl::string_view` for the following descriptor APIs, +which opens up memory savings: + +* `MessageLite::GetTypeName` +* `UnknownField::length_delimited` +* Descriptor API name functions, such as `FieldDescriptor::full_name` + +We expect future breaking releases to continue migrating additional APIs to +`absl::string_view`. + +In most cases, you should try to update types to use `absl::string_view` where +safe, or explicitly copy to the original type where needed. You may need to +update callers as well if this is returned in a function. + +If the string returned by the affected API methods is being used as: + + + + + + + + + + + + + + + + + + +
TypeMigration
+

std::string

+ 		+

Explicitly convert to std::string to preserve the existing behavior.

+

Or, switch to the more performant absl::string_view

+
+

const std::string&

+ 		+

Migrate to absl::string_view

+

If infeasible (such as due to large number of dependencies), copying to a std::string might be easier.

+
+

const std::string*

+

const char*

+ 		+

If nullable, migrate to std::optional<absl::string_view>.

+

Otherwise, migrate to absl::string_view.

+

Be careful when calling data() since absl::string_view isn't guaranteed to be null-terminated. +

+ +For common containers and other APIs, you may be able to migrate to variants +compatible with `absl::string_view`. Below are some common examples. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CategoryPre-MigrationMigration
Insertion into std::vector<std::string> +

push_back()

+

push_front()

+

push()

+ 		+

emplace_back()

+

emplace_front()

+

emplace()

+
Insertion for map or sets +

set.insert(key)

+

map.insert({key, value})

+

map.insert({key,
{value_params...}})

+ 		+

set.emplace(key)

+

map.emplace(key, value)

+

map.try_emplace(key,
value_params...)

+
Lookup for map or sets +

find()

+

count()

+

contains()

+ 		+

Migrate to Abseil containers.

+

Or, define a transparent comparator.

+

std::set<std::string, std::less<>>
+ std::map<std::string, T, std::less<>>

+

See https://abseil.io/tips/144

+
String Concatenation +

operator+

+

operator+=

+ 		+

absl::StrCat()

+

absl::StrAppend()

+

These are recommended for performance reasons anyways. See https://abseil.io/tips/3.

+
+ +See also [https://abseil.io/tips/1](https://abseil.io/tips/1) for general tips +around using `absl::string_view`. + +### Poison MSVC + Bazel + +Bazel users on Windows should switch to using clang-cl by adding the following +to their project, like in this +[example](https://github.com/protocolbuffers/protobuf/commit/117e7bbe74ac7c7faa9b6f44c1b22de366302854#diff-48bcd3965c4a015a8f61ad82b225790209baef37363ee0478519536a620a85e5). + +**.bazelrc** + +```bazel +common --enable_platform_specific_config build:windows +--extra_toolchains=@local_config_cc//:cc-toolchain-x64_windows-clang-cl +--extra_execution_platforms=//:x64_windows-clang-cl +``` + +**MODULE.bazel** + +```bazel +bazel_dep(name = "platforms", version = "0.0.10") +bazel_dep(name = "rules_cc", version = "0.0.17") + +# For clang-cl configuration +cc_configure = use_extension("@rules_cc//cc:extensions.bzl", "cc_configure_extension") +use_repo(cc_configure, "local_config_cc") +``` + +**WORKSPACE** + +```bazel +load("//:protobuf_deps.bzl", "PROTOBUF_MAVEN_ARTIFACTS", "protobuf_deps") + +protobuf_deps() + +load("@rules_cc//cc:repositories.bzl", "rules_cc_dependencies", "rules_cc_toolchains") + +rules_cc_dependencies() + +rules_cc_toolchains() +``` + +**BUILD** + +For users that need compatibility with Bazel 8 only. + +```bazel +platform( + name = "x64_windows-clang-cl", + constraint_values = [ + "@platforms//cpu:x86_64", + "@platforms//os:windows", + "@bazel_tools//tools/cpp:clang-cl", + ], +) +``` + +For users that need compatibility with Bazel 7 and 8. + +```bazel +platform( + name = "x64_windows-clang-cl", + constraint_values = [ + "@platforms//cpu:x86_64", + "@platforms//os:windows", + # See https://github.com/bazelbuild/rules_cc/issues/330. + "@rules_cc//cc/private/toolchain:clang-cl", + ], +) +``` + +Users can also temporarily silence the error by setting the opt-out flag +`--define=protobuf_allow_msvc=true` until the next breaking release. + +Alternatively, users that wish to continue using MSVC may switch to using CMake. +This can be done with +[Visual Studio](https://learn.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio?view=msvc-170), +or by supplying the CMake command-line an MSVC generator. For example: + +```cmake +cmake -G "Visual Studio 17 2022" -A Win64 . +``` + +### ctype Removed from FieldDescriptor Options {#ctype-removed} + +We stopped exposing the `ctype` from `FieldDescriptor` options. You can use the +`FieldDescriptor::cpp_string_type()` API, added in the +[v28 release](https://github.com/protocolbuffers/protobuf/releases/tag/v28.0), +in its place. + +### Modified Debug APIs to Redact Sensitive Fields {#debug-redaction} + +The Protobuf C++ debug APIs (including Protobuf AbslStringify, +`proto2::ShortFormat`, `proto2::Utf8Format`, `Message::DebugString`, +`Message::ShortDebugString`, `Message::Utf8DebugString`) changed to redact +sensitive fields annotated by `debug_redact`; the outputs of these APIs contain +a per-process randomized prefix, and are no longer parseable by Protobuf +TextFormat Parsers. Users should adopt the new redacted debug format for most +cases requiring a human-readable output (such as logging), or consider switching +to binary format for serialization and deserialization. Users who need the old +deserializable format can use `TextFormat.printer().printToString(proto)`, but +this does not redact sensitive fields and so should be used with caution. + +Read more about this in the +[news article released December 4, 2024](/news/2024-12-04.md). + +### Removed Deprecated APIs {#remove-deprecated} + +We removed the following public runtime APIs, which have been marked deprecated +(such as `ABSL_DEPRECATED`) for at least one minor or major release and that are +obsolete or replaced. + +**API:** +[`Arena::CreateMessage`](https://github.com/protocolbuffers/protobuf/blob/f4b57b98b08aec8bc52e6a7b762edb7a1b9e8883/src/google/protobuf/arena.h#L179) + +**Replacement:** +[`Arena::Create`](https://github.com/protocolbuffers/protobuf/blob/f4b57b98b08aec8bc52e6a7b762edb7a1b9e8883/src/google/protobuf/arena.h#L191) + +**API:** +[`Arena::GetArena`](https://github.com/protocolbuffers/protobuf/blob/237332ef92daf83a53e76decd6ac43c3fcee782b/src/google/protobuf/arena.h#L346) + +**Replacement:** `value->GetArena()` + +**API:** +[`RepeatedPtrField::ClearedCount`](https://github.com/protocolbuffers/protobuf/blame/f4b57b98b08aec8bc52e6a7b762edb7a1b9e8883/src/google/protobuf/repeated_ptr_field.h#L1157) + +**Replacement:** Migrate to Arenas +([migration guide](https://protobuf.dev/support/migration/#cleared-elements)). + +**API:** +[`JsonOptions`](https://github.com/protocolbuffers/protobuf/blob/f4b57b98b08aec8bc52e6a7b762edb7a1b9e8883/src/google/protobuf/util/json_util.h#L22) + +**Replacement:** `JsonPrintOptions` + +### Dropped C++14 Support {#drop-cpp-14} + +This release dropped C++ 14 as the minimum supported version and raised it to +17, as per the +[Foundational C++ Support matrix](https://github.com/google/oss-policies-info/blob/main/foundational-cxx-support-matrix.md). + +Users should upgrade to C++17. + +### Introduced ASAN Poisoning After Clearing Oneof Messages on Arena + +This change added a hardening check that affects C++ protobufs using Arenas. +Oneof messages allocated on the protobuf arena are now cleared in debug and +poisoned in ASAN mode. After calling clear, future attempts to use the memory +region will cause a crash in ASAN as a use-after-free error. + +This implementation requires C++17. + +### Dropped our C++ CocoaPods release + +We dropped our C++ CocoaPods release, which has been broken since v4.x.x. C++ +users should use our +[GitHub release](https://github.com/protocolbuffers/protobuf/releases) directly +instead. + +### Changes in Python {#python} + +Python bumped its major version from 5.29.x to 6.30.x. + +#### Dropped Python 3.8 Support + +The minimum supported Python version is 3.9. Users should upgrade. + +#### Removed bazel/system_python.bzl Alias {#python-remove-alias} + +We removed the legacy `bazel/system_python.bzl` alias. + +Remove direct references to `system_python.bzl` in favor of using +`protobuf_deps.bzl` instead. Use `python/dist/system_python.bzl` where it was +moved +[in v5.27.0](https://github.com/protocolbuffers/protobuf/commit/d7f032ad1596ceeabd45ca1354516c39b97b2551) +if you need a direct reference. + +#### Field Setter Validation Changes {#python-setter-validation} + +Python's and upb's field setters now validate closed enums under edition 2023. +Closed enum fields updated with invalid values generate errors. + +#### Removed Deprecated py_proto_library Macro + +The deprecated internal `py_proto_library` Bazel macro in `protobuf.bzl` was +removed. It was replaced by the official `py_proto_library` which was moved to +protobuf in `bazel/py_proto_library` in v29.x. This implementation was +previously available in `rules_python` prior to v29.x. + +#### Remove Deprecated APIs {#python-remove-apis} + +We removed the following public runtime APIs, which had been marked deprecated +for at least one minor or major release. + +##### Reflection Methods + +**APIs:** +[`reflection.ParseMessage`](https://github.com/protocolbuffers/protobuf/blob/7f395af40e86e00b892e812beb67a03564884756/python/google/protobuf/reflection.py#L40), +[`reflection.MakeClass`](https://github.com/protocolbuffers/protobuf/blob/7f395af40e86e00b892e812beb67a03564884756/python/google/protobuf/reflection.py#L66) + +**Replacement:** `message_factory.GetMessageClass()` + +##### RPC Service Interfaces + +**APIs:** +[`service.RpcException`](https://github.com/protocolbuffers/protobuf/blob/21c545c8c5cec0b052dc7715b778f0353d37d02c/python/google/protobuf/service.py#L23), +[`service.Service`](https://github.com/protocolbuffers/protobuf/blob/21c545c8c5cec0b052dc7715b778f0353d37d02c/python/google/protobuf/service.py#L28), +[`service.RpcController`](https://github.com/protocolbuffers/protobuf/blob/21c545c8c5cec0b052dc7715b778f0353d37d02c/python/google/protobuf/service.py#L97), +and +[`service.RpcChannel`](https://github.com/protocolbuffers/protobuf/blob/21c545c8c5cec0b052dc7715b778f0353d37d02c/python/google/protobuf/service.py#L180) + +**Replacement:** Starting with version 2.3.0, RPC implementations should not try +to build on these, but should instead provide code generator plugins which +generate code specific to the particular RPC implementation. + +##### MessageFactory and SymbolDatabase Methods + +**APIs:** +[`MessageFactory.GetPrototype`](https://github.com/protocolbuffers/protobuf/blob/7f395af40e86e00b892e812beb67a03564884756/python/google/protobuf/message_factory.py#L145), +[`MessageFactory.CreatePrototype`](https://github.com/protocolbuffers/protobuf/blob/7f395af40e86e00b892e812beb67a03564884756/python/google/protobuf/message_factory.py#L165), +[`MessageFactory.GetMessages`](https://github.com/protocolbuffers/protobuf/blob/7f395af40e86e00b892e812beb67a03564884756/python/google/protobuf/message_factory.py#L185), +[`SymbolDatabase.GetPrototype`](https://github.com/protocolbuffers/protobuf/blob/7f395af40e86e00b892e812beb67a03564884756/python/google/protobuf/symbol_database.py#L54), +[`SymbolDatabase.CreatePrototype`](https://github.com/protocolbuffers/protobuf/blob/7f395af40e86e00b892e812beb67a03564884756/python/google/protobuf/symbol_database.py#L60), +and +[`SymbolDatabase.GetMessages`](https://github.com/protocolbuffers/protobuf/blob/7f395af40e86e00b892e812beb67a03564884756/python/google/protobuf/symbol_database.py#L66) + +**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. + +#### Python setdefault Behavior Change for Map Fields + +`setdefault` is similar to `dict` for `ScalarMap`, except that both key and +value must be set. `setdefault` is rejected for `MessageMaps`. + +#### Python Nested Message Class \_\_qualname\_\_ Contains the Outer Message Name + +Python nested message class `__qualname__` now contains the outer message name. +Previously, `__qualname__` had the same result with `__name__` for nested +message, in that the outer message name was not included. + +For example: + +```python +message Foo { + message Bar { + bool bool_field = 1; + } +} +nested = test_pb2.Foo.Bar() +self.assertEqual('Bar', nested.__class__.__name__) +self.assertEqual('Foo.Bar', nested.__class__.__qualname__) # It was 'Bar' before +``` + +### Changes in Objective-C {#objc} + +**This is the first breaking release for Objective-C**. + +Objective-C bumped its major version from 3.x.x to 4.30.x. + +#### Overhauled Unknown Field Handling APIs Deprecating Most of the Existing APIs {#objc-field-handling} + +We deprecated `GPBUnknownFieldSet` and replaced it with `GPBUnknownFields`. The +new type preserves the ordering of unknown fields from the original input or API +calls, to ensure any semantic meaning to the ordering is maintained when a +message is written back out. + +As part of this, the `GPBUnknownField` type also has APIs changes, with almost +all of the existing APIs deprecated and new ones added. + +Deprecated property APIs: + +* `varintList` +* `fixed32List` +* `fixed64List` +* `lengthDelimitedList` +* `groupList` + +Deprecated modification APIs: + +* `addVarint:` +* `addFixed32:` +* `addFixed64:` +* `addLengthDelimited:` +* `addGroup:` + +Deprecated initializer `initWithNumber:`. + +New property APIs: + +* `type` +* `varint` +* `fixed32` +* `fixed64` +* `lengthDelimited` +* `group` + +This type models a single field number in its value, rather than *grouping* all +the values for a given field number. The APIs for creating new fields are the +`add*` APIs on the `GPBUnknownFields` class. + +We also deprecated `-[GPBMessage unknownFields]`. In its place, there are new +APIs to extract and update the unknown fields of the message. + +#### Removed Deprecated APIs {#objc-remove-apis} + +We removed the following public runtime APIs, which had been marked deprecated +for at least one minor or major release. + +##### GPBFileDescriptor + +**API:** +[-[`GPBFileDescriptor` syntax]](https://github.com/protocolbuffers/protobuf/blob/44bd65b2d3c0470d91a23cc14df5ffb1ab0af7cd/objectivec/GPBDescriptor.h#L118-L119) + +**Replacement:** Obsolete. + +##### GPBMessage mergeFrom:extensionRegistry + +**API:** +[-[`GPBMessage mergeFrom:extensionRegistry:`]](https://github.com/protocolbuffers/protobuf/blob/44bd65b2d3c0470d91a23cc14df5ffb1ab0af7cd/objectivec/GPBMessage.h#L258-L261) + +**Replacement:** +[-[`GPBMessage mergeFrom:extensionRegistry:error:`]](https://github.com/protocolbuffers/protobuf/blob/44bd65b2d3c0470d91a23cc14df5ffb1ab0af7cd/objectivec/GPBMessage.h#L275-L277) + +##### GPBDuration timeIntervalSince1970 + +**API:** +[-[`GPBDuration timeIntervalSince1970`]](https://github.com/protocolbuffers/protobuf/blob/29fca8a64b62491fb0a2ce61878e70eda88dde98/objectivec/GPBWellKnownTypes.h#L95-L100) + +**Replacement:** +[-[`GPBDuration timeInterval`]](https://github.com/protocolbuffers/protobuf/blob/29fca8a64b62491fb0a2ce61878e70eda88dde98/objectivec/GPBWellKnownTypes.h#L74-L89) + +##### GPBTextFormatForUnknownFieldSet + +**API:** +[`GPBTextFormatForUnknownFieldSet()`](https://github.com/protocolbuffers/protobuf/blob/29fca8a64b62491fb0a2ce61878e70eda88dde98/objectivec/GPBUtilities.h#L32-L43) + +**Replacement:** Obsolete - Use +[`GPBTextFormatForMessage()`](https://github.com/protocolbuffers/protobuf/blob/29fca8a64b62491fb0a2ce61878e70eda88dde98/objectivec/GPBUtilities.h#L20-L30), +which includes any unknown fields. + +##### GPBUnknownFieldSet + +**API:** +[`GPBUnknownFieldSet`](https://github.com/protocolbuffers/protobuf/blob/224573d66a0cc958c76cb43d8b2eb3aa7cdb89f2/objectivec/GPBUnknownFieldSet.h) + +**Replacement:** +[`GPBUnknownFields`](https://github.com/protocolbuffers/protobuf/blob/224573d66a0cc958c76cb43d8b2eb3aa7cdb89f2/objectivec/GPBUnknownFields.h) + +##### GPBMessage unknownFields + +**API:** +[`GPBMessage unknownFields` property](https://github.com/protocolbuffers/protobuf/blob/224573d66a0cc958c76cb43d8b2eb3aa7cdb89f2/objectivec/GPBMessage.h#L73-L76) + +**Replacement:** +[-[`GPBUnknownFields initFromMessage:`]](https://github.com/protocolbuffers/protobuf/blob/224573d66a0cc958c76cb43d8b2eb3aa7cdb89f2/objectivec/GPBUnknownFields.h#L30-L38), +[-[`GPBMessage mergeUnknownFields:extensionRegistry:error:`]](https://github.com/protocolbuffers/protobuf/blob/f26bdff7cc0bb7e8ed88253ba16f81614a26cf16/objectivec/GPBMessage.h#L506-L528), +and +[-[`GPBMessage clearUnknownFields`]](https://github.com/protocolbuffers/protobuf/blob/224573d66a0cc958c76cb43d8b2eb3aa7cdb89f2/objectivec/GPBMessage.h#L497-L504C9) + +#### Removed Deprecated Runtime APIs for Old Gencode {#objc-remove-apis-gencode} + +This release removed deprecated runtime methods that supported the Objective-C +gencode from before the 3.22.x release. The library also issues 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. + +### Poison Pill Warnings {#poison} + +We updated poison pills to emit warnings for old gencode + new runtime +combinations that work under the new rolling upgrade policy, but will break in +the *next* major bump. For example, Python 4.x.x gencode should work against +5.x.x runtime but warn of upcoming breakage against 6.x.x runtime. + +### Changes to UTF-8 Enforcement in C# and Ruby {#utf-8-enforcement} + +We included 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 + +We fixed non-conformance in JSON parsing of strings in numeric fields per the +[JSON spec](https://protobuf.dev/programming-guides/json/). + +This fix is not accompanied by a major version bump, but Ruby and PHP now raise +errors for non-numeric strings (such as `""`, `"12abc"`, `"abc"`) in numeric +fields. v29.x includes a warning for these error cases. + ## Compiler Changes in v22.0 {#compiler-22} ### JSON Field Name Conflicts {#json-field-names} @@ -39,9 +610,9 @@ Source of changes: In v22.0, we removed all Autotools support from the protobuf compiler and the C++ runtime. If you're using Autotools to build either of these, you must -migrate to [CMake](http://cmake.org) or -[Bazel](http://bazel.build). We have some -[dedicated instructions](https://github.com/protocolbuffers/protobuf/blob/main/cmake/README) +migrate to [CMake](http://cmake.org) or [Bazel](http://bazel.build). We have +some +[dedicated instructions](https://github.com/protocolbuffers/protobuf/blob/main/cmake/README.md) for setting up protobuf with CMake. ### Abseil Dependency {#abseil} @@ -50,8 +621,8 @@ Source of changes: [PR #10416](https://github.com/protocolbuffers/protobuf/pull/10416) With v22.0, we've taken on an explicit dependency on -[Abseil](https://github.com/abseil/abseil-cpp). This allowed us to -remove most of our +[Abseil](https://github.com/abseil/abseil-cpp). This allowed us to remove most +of our [stubs](https://github.com/protocolbuffers/protobuf/tree/21.x/src/google/protobuf/stubs), which were branched from old internal code that later became Abseil. There are a number of subtle behavior changes, but most should be transparent to users. Some @@ -65,24 +636,24 @@ notable changes include: * **tables** - Instead of STL sets/maps, we now use Abseil's `flat_hash_map`, `flat_hash_set`, `btree_map`, and `btree_set`. These are more efficient and - allow for [heterogeneous lookup](https://abseil.io/tips/144). - This should be mostly invisible to users, but may cause some subtle behavior - changes related to table ordering. + allow for [heterogeneous lookup](https://abseil.io/tips/144). This should be + mostly invisible to users, but may cause some subtle behavior changes + related to table ordering. * **logging** - Abseil's - [logging library](https://abseil.io/docs/cpp/guides/logging) is - very similar to our old logging code, with just a slightly different - spelling (for example, `ABSL_CHECK` instead of `GOOGLE_CHECK`). The biggest - difference is that it doesn't support exceptions, and will now always crash - when `FATAL` assertions fail. (Previously we had a `PROTOBUF_USE_EXCEPTIONS` - flag to switch to exceptions.) Since these only occur when serious issues - are encountered, we feel unconditional crashing is a suitable response. + [logging library](https://abseil.io/docs/cpp/guides/logging) is very similar + to our old logging code, with just a slightly different spelling (for + example, `ABSL_CHECK` instead of `GOOGLE_CHECK`). The biggest difference is + that it doesn't support exceptions, and will now always crash when `FATAL` + assertions fail. (Previously we had a `PROTOBUF_USE_EXCEPTIONS` flag to + switch to exceptions.) Since these only occur when serious issues are + encountered, we feel unconditional crashing is a suitable response. Source of logging changes: [PR #11623](https://github.com/protocolbuffers/protobuf/pull/11623) * **Build dependency** - A new build dependency can always cause breakages for downstream users. We require - [Abseil LTS 20230117](https://github.com/abseil/abseil-cpp/releases/tag/20230117.rc1) + [Abseil LTS 20230125](https://github.com/abseil/abseil-cpp/releases/tag/20230125.0) or later to build. * For Bazel builds, Abseil will be automatically downloaded and built at a @@ -167,7 +738,6 @@ After: void F() { auto time = (google::protobuf::util::TimeUtil::GetCurrentTime)(); } - ``` ## C++20 Support {#cpp20} @@ -175,13 +745,12 @@ void F() { Source of changes: [PR #10796](https://github.com/protocolbuffers/protobuf/pull/10796) To support C++20, we've reserved the new -[keywords](https://en.cppreference.com/w/cpp/keyword) in C++ -generated protobuf code. As with other reserved keywords, if you use them for -any fields, enums, or messages, we will add an underscore suffix to make them -valid C++. For example, a `concept` field will generate a `concept_()` getter. -In the scenario where you have existing protos that use these keywords, you'll -need to update the C++ code that references them to add the appropriate -underscores. +[keywords](https://en.cppreference.com/w/cpp/keyword) in C++ generated protobuf +code. As with other reserved keywords, if you use them for any fields, enums, or +messages, we will add an underscore suffix to make them valid C++. For example, +a `concept` field will generate a `concept_()` getter. In the scenario where you +have existing protos that use these keywords, you'll need to update the C++ code +that references them to add the appropriate underscores. ### Final Classes {#final-classes} @@ -236,8 +805,8 @@ different arenas. Source of changes: [PR #11625](https://github.com/protocolbuffers/protobuf/pull/11625) -For v22.0 we’ve started cleaning up the `Map` API to make it more consistent -with Abseil and STL. Notably, we’ve replaced the `MapPair` class with an alias +For v22.0 we've started cleaning up the `Map` API to make it more consistent +with Abseil and STL. Notably, we've replaced the `MapPair` class with an alias to `std::pair`. This should be transparent for most users, but if you were using the class directly you may need to update your code.