From 9bbf481e39e1c9b8c77b35919c3cd66fd32ce363 Mon Sep 17 00:00:00 2001 From: Protocol Buffer Team Date: Wed, 2 Oct 2024 18:59:49 +0000 Subject: [PATCH] This change to the documentation includes the following: * Adds news entries for changes to Bazel builds, and to announce upcoming breaking changes in v30.x. * Updates the Extension Declaration documentation to remove information about proto2, and to add information about `MessageSet` handling. * Fixes the RSS feed. PiperOrigin-RevId: 681540452 Change-Id: I2c6f098b85e2c128bf901c5ff089c02eca2048cd --- content/news/2024-10-01.md | 49 +++ content/news/2024-10-02.md | 282 ++++++++++++++++++ content/news/_index.md | 5 + content/news/v29.md | 52 ++++ .../extension_declarations.md | 18 +- layouts/_default/rss.xml | 64 ++++ 6 files changed, 464 insertions(+), 6 deletions(-) create mode 100644 content/news/2024-10-01.md create mode 100644 content/news/2024-10-02.md create mode 100644 content/news/v29.md create mode 100644 layouts/_default/rss.xml diff --git a/content/news/2024-10-01.md b/content/news/2024-10-01.md new file mode 100644 index 000000000..9a2ad57d9 --- /dev/null +++ b/content/news/2024-10-01.md @@ -0,0 +1,49 @@ ++++ +title = "Changes Announced on October 1, 2024" +linkTitle = "October 1, 2024" +toc_hide = "true" +description = "Changes announced for Protocol Buffers on October 1, 2024." +type = "docs" ++++ + +## Bazel and Proto Rules + +There are upcoming changes to the way that Bazel will work for protobuf builds. +These changes require awareness in the first stage, and action by project owners +before the second stage. + +### Stage 1 + +With the release of Bazel 8, proto rules (`proto_library`, `cc_proto_library`, +`java_proto_library`, `java_lite_proto_library`, and `py_proto_library`) will be +removed from the Bazel project. The will be added to the Protocol Buffers +project in v29. Bazel will be updated to automatically use the rules from the +protobuf project, so the change is initially a no-op for project owners. + +After the release of Bazel 8 and before the release of Bazel 9, users will need +to explicitly `load` the rules from the Protocol Buffers project repository. The +automatic use of the rules is only temporary to support the migration. + +Users should add the following `load()` statements to any `BUILD` or `.bzl` +files that use these proto rules. Note that these require Protobuf v29.0 or +higher. + +```bazel +load("@protobuf//bazel:proto_library.bzl", "proto_library") + +load("@protobuf//bazel:cc_proto_library.bzl", "cc_proto_library") +load("@protobuf//bazel:java_proto_library.bzl", "java_proto_library") +load("@protobuf//bazel:java_lite_proto_library.bzl", "java_lite_proto_library") +load("@protobuf//bazel:py_proto_library.bzl", "py_proto_library") +``` + +### Stage 2 + +When Bazel 9 is released, the automatic loading of the protobuf library’s rules +will be removed. At that point, you will need to have `load` statements in your +Bazel build files. + +### End Goal + +Once the rules are in the protobuf repo, we intend to address common user +requests, such as using prebuilts for the proto compiler where possible. diff --git a/content/news/2024-10-02.md b/content/news/2024-10-02.md new file mode 100644 index 000000000..c4ddf41d2 --- /dev/null +++ b/content/news/2024-10-02.md @@ -0,0 +1,282 @@ ++++ +title = "Changes Announced on October 2, 2024" +linkTitle = "October 2, 2024" +toc_hide = "true" +description = "Changes announced for Protocol Buffers on October 2, 2024." +type = "docs" ++++ + +The following sections cover planned breaking changes in the v30 release, +expected in 2025 Q1. These describe changes as we anticipate them being +implemented, but due to the flexible nature of software some of these changes +may not land or may vary from how they are described in this topic. + +## Changes in C++ {#cpp} + +C++ will bump its major version from 5.29.x to 6.30.x. + +### Descriptor APIs {#descriptor-apis} + +v30 will update return types in descriptor (such as `full_name`) to be +`absl::string_view`. This opens up memory savings in descriptors. + +v28 introduced the `PROTOBUF_FUTURE_STRING_VIEW_RETURN_TYPE` macro, which you +can use in the meantime to enable the updated return type ahead of the breaking +release. The v30 release will flip the default and remove the macro. + +### ctype Removed from FieldDescriptor Options {#ctype-removed} + +v30 will stop 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. + +### Replace CMake Submodules with Fetched Deps {#replace-cmake-submods} + +v30 will remove submodules and switches to upb's old CMake pattern of fetching +dependencies. + +If you use installed packages, you won't be affected. It could break some CMake +workflows. + +### Remove Deprecated APIs {#remove-deprecated} + +v30 will remove 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. + +#### Arena::CreateMessage + +**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) + +#### Arena::GetArena + +**API:** +[`Arena::GetArena`](https://github.com/protocolbuffers/protobuf/blob/237332ef92daf83a53e76decd6ac43c3fcee782b/src/google/protobuf/arena.h#L346) + +**Replacement:** `value->GetArena()` + +#### RepeatedPtrField::ClearedCount + +**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)). + +#### JsonOptions + +**API:** +[`JsonOptions`](https://github.com/protocolbuffers/protobuf/blob/f4b57b98b08aec8bc52e6a7b762edb7a1b9e8883/src/google/protobuf/util/json_util.h#L22) + +**Replacement:** `JsonPrintOptions` + +### Dropping C++14 Support {#drop-cpp-14} + +This release will drop C++ 14 as the minimum supported version and raise it to +17, as per the +[Foundational C++ Support matrix](https://github.com/google/oss-policies-info/blob/main/foundational-cxx-support-matrix.md). + +Per [our policies](https://protobuf.dev/support/version-support/), we do not +consider this to be a breaking change. + +## Changes in JRuby {#jruby} + +v30 will flip the default implementation for JRuby to FFI, which may be breaking +for some JRuby users. + +Note that this change doesn't create a Ruby major version bump because JRuby is +[not officially supported](/support/version-support/#ruby). + +## Changes in Python {#python} + +Python will bump its major version from 5.29.x to 6.30.x. + +### Dropping Python 3.8 Support + +As per our official Python support policy, we will be dropping support for +Python 3.8 and lower. This means the minimum supported Python version is 3.9. + +### Remove bazel/system_python.bzl Alias {#python-remove-alias} + +v30 will remove 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 will be fixed in v30 to validate closed enums +under edition 2023. Closed enum fields updated with invalid values will generate +errors. + +### Remove Deprecated APIs {#python-remove-apis} + +v30 will remove the following public runtime APIs, which have been marked +deprecated for at least one minor or major release and are obsolete or replaced. + +#### 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()`. + +## Changes in Objective-C {#objc} + +**This will be the first breaking release for Objective-C**. + +Objective-C will bump its major version from 3.x.x to 4.30.x. + +### Overhaul Unknown Field Handling APIs Deprecating Most of the Existing APIs {#objc-field-handling} + +v30 will deprecate `GPBUnknownFieldSet` and replace it with `GPBUnknownFields`. +The new type will preserve 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 its APIs changed, with +almost all of the existing APIs becoming 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 will model 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. + +v30 will also deprecate `-[GPBMessage unknownFields]`. In its place, there will +be new APIs to extract and update the unknown fields of the message. + +### Remove Deprecated APIs {#objc-remove-apis} + +v30 will remove the following public runtime APIs, which have been marked +deprecated for at least one minor or major release and are obsolete or replaced. + +#### 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) + +## Other Changes {#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. + +### Poison Pill Warnings {#poison} + +v30 will update 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, Java 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} + +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. diff --git a/content/news/_index.md b/content/news/_index.md index 553787ac9..f89bdb220 100644 --- a/content/news/_index.md +++ b/content/news/_index.md @@ -20,6 +20,10 @@ New news topics will also be published to the The following news topics provide information in the reverse order in which it was released. +* [October 2, 2024](/news/2024-10-02) - Breaking + changes in the upcoming 30.x release +* [October 1, 2024](/news/2024-10-01) - Changes to + Bazel builds * [June 26, 2024](/news/2024-06-26) - Dropping support for building Protobuf Java from source with Maven * [February 27, 2024](/news/2024-02-27) - Dropping @@ -80,6 +84,7 @@ release notes will be more complete. Also, not everything from the chronological listing will be in these topics, as some content is not specific to a particular release. +* [Version 29.x](/news/v29) * [Version 26.x](/news/v26) * [Version 25.x](/news/v25) * [Version 24.x](/news/v24) diff --git a/content/news/v29.md b/content/news/v29.md new file mode 100644 index 000000000..c0834b4a0 --- /dev/null +++ b/content/news/v29.md @@ -0,0 +1,52 @@ ++++ +title = "News Announcements for Version 29.x" +linkTitle = "Version 29.x" +toc_hide = "true" +description = "Changes announced for Protocol Buffers version 29.x." +type = "docs" ++++ + +The following announcements are specific to Version 29.x. For information +presented chronologically, see [News](/news). + +## Bazel and Proto Rules + +There are upcoming changes to the way that Bazel will work for protobuf builds. +These changes require awareness in the first stage, and action by project owners +before the second stage. + +### Stage 1 + +With the release of Bazel 8, proto rules (`proto_library`, `cc_proto_library`, +`java_proto_library`, `java_lite_proto_library`, and `py_proto_library`) will be +removed from the Bazel project. The will be added to the Protocol Buffers +project in v29. Bazel will be updated to automatically use the rules from the +protobuf project, so the change is initially a no-op for project owners. + +After the release of Bazel 8 and before the release of Bazel 9, users will need +to explicitly `load` the rules from the Protocol Buffers project repository. The +automatic use of the rules is only temporary to support the migration. + +Users should add the following `load()` statements to any `BUILD` or `.bzl` +files that use these proto rules. Note that these require Protobuf v29.0 or +higher. + +```bazel +load("@protobuf//bazel:proto_library.bzl", "proto_library") + +load("@protobuf//bazel:cc_proto_library.bzl", "cc_proto_library") +load("@protobuf//bazel:java_proto_library.bzl", "java_proto_library") +load("@protobuf//bazel:java_lite_proto_library.bzl", "java_lite_proto_library") +load("@protobuf//bazel:py_proto_library.bzl", "py_proto_library") +``` + +### Stage 2 + +When Bazel 9 is released, the automatic loading of the protobuf library’s rules +will be removed. At that point, you will need to have `load` statements in your +Bazel build files. + +### End Goal + +Once the rules are in the protobuf repo, we intend to address common user +requests, such as using prebuilts for the proto compiler where possible. diff --git a/content/programming-guides/extension_declarations.md b/content/programming-guides/extension_declarations.md index 7089f959d..e68a3c275 100644 --- a/content/programming-guides/extension_declarations.md +++ b/content/programming-guides/extension_declarations.md @@ -7,7 +7,7 @@ type = "docs" ## Introduction {#intro} @@ -15,9 +15,9 @@ freshness: { owner: 'shaod' reviewed: '2023-09-06' } This page describes in detail what extension declarations are, why we need them, and how we use them. -**NOTE:** Extension declarations are mostly used in proto2, as proto3 does not -support extensions at this time (except for +**NOTE:** Proto3 does not support extensions (except for [declaring custom options](/programming-guides/proto3/#customoptions)). +Extensions are fully supported in proto2 and editions though. If you need an introduction to extensions, read this [extensions guide](https://protobuf.dev/programming-guides/proto2/#extensions) @@ -160,9 +160,15 @@ declarations to declare the field number and type for each extension in the parent message. The extension declarations serve as a registry of all the parent message's extensions, and protoc will enforce that there are no field number conflicts. When you add a new -extension, choose the number by just incrementing by one the previously added -extension number. Whenever you delete an extension, make sure to mark the field -number `reserved` to eliminate the risk of accidentally reusing +extension, choose the next available number usually by just incrementing by one +the previously added extension number. + +**TIP:** There is a [special guidance](#message-set) for +`MessageSet` which provides a script to help pick +the next available number. + +Whenever you delete an extension, make sure to mark the field number `reserved` +to eliminate the risk of accidentally reusing it. This convention is only a recommendation--the protobuf team does not have the diff --git a/layouts/_default/rss.xml b/layouts/_default/rss.xml new file mode 100644 index 000000000..9345ab707 --- /dev/null +++ b/layouts/_default/rss.xml @@ -0,0 +1,64 @@ + +{{- $authorEmail := "" }} +{{- with site.Params.author }} + {{- if reflect.IsMap . }} + {{- with .email }} + {{- $authorEmail = . }} + {{- end }} + {{- end }} +{{- end }} + +{{- $authorName := "" }} +{{- with site.Params.author }} + {{- if reflect.IsMap . }} + {{- with .name }} + {{- $authorName = . }} + {{- end }} + {{- else }} + {{- $authorName = . }} + {{- end }} +{{- end }} + +{{- $pctx := . }} +{{- if .IsHome }}{{ $pctx = .Site }}{{ end }} +{{- $pages := slice }} +{{- if or $.IsHome $.IsSection }} +{{- $pages = $pctx.RegularPages }} +{{- else }} +{{- $pages = $pctx.Pages }} +{{- end }} +{{- $limit := .Site.Config.Services.RSS.Limit }} +{{- if ge $limit 1 }} +{{- $pages = $pages | first $limit }} +{{- end }} +{{- printf "" | safeHTML }} + + + {{ if eq .Title .Site.Title }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{ . }} on {{ end }}{{ .Site.Title }}{{ end }} + {{ .Permalink }} + Recent content {{ if ne .Title .Site.Title }}{{ with .Title }}in {{ . }} {{ end }}{{ end }}on {{ .Site.Title }} + Hugo + {{ site.Language.LanguageCode }}{{ with $authorEmail }} + {{.}}{{ with $authorName }} ({{ . }}){{ end }}{{ end }}{{ with $authorEmail }} + {{ . }}{{ with $authorName }} ({{ . }}){{ end }}{{ end }}{{ with .Site.Copyright }} + {{ . }}{{ end }}{{ if not .Date.IsZero }} + {{ (index $pages.ByLastmod.Reverse 0).Lastmod.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}{{ end }} + {{- with .OutputFormats.Get "RSS" }} + {{ printf "" .Permalink .MediaType | safeHTML }} + {{- end }} + {{- range $pages }} + + {{ .Title }} + {{ .Permalink }} + {{ .PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }} + {{- with $authorEmail }}{{ . }}{{ with $authorName }} ({{ . }}){{ end }}{{ end }} + {{ .Permalink }} + {{ .Summary | transform.XMLEscape | safeHTML }} + + {{- end }} + +