Skip to content

Commit 7375015

Browse files
LogofileLogofile
authored
Merge pull request #188 from Logofile/sync
Documentation update
2 parents 89a0c1c + 9bbf481 commit 7375015

File tree

6 files changed

+464
-6
lines changed

6 files changed

+464
-6
lines changed

‎content/news/2024-10-01.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
+++
2+
title = "Changes Announced on October 1, 2024"
3+
linkTitle = "October 1, 2024"
4+
toc_hide = "true"
5+
description = "Changes announced for Protocol Buffers on October 1, 2024."
6+
type = "docs"
7+
+++
8+
9+
## Bazel and Proto Rules
10+
11+
There are upcoming changes to the way that Bazel will work for protobuf builds.
12+
These changes require awareness in the first stage, and action by project owners
13+
before the second stage.
14+
15+
### Stage 1
16+
17+
With the release of Bazel 8, proto rules (`proto_library`, `cc_proto_library`,
18+
`java_proto_library`, `java_lite_proto_library`, and `py_proto_library`) will be
19+
removed from the Bazel project. The will be added to the Protocol Buffers
20+
project in v29. Bazel will be updated to automatically use the rules from the
21+
protobuf project, so the change is initially a no-op for project owners.
22+
23+
After the release of Bazel 8 and before the release of Bazel 9, users will need
24+
to explicitly `load` the rules from the Protocol Buffers project repository. The
25+
automatic use of the rules is only temporary to support the migration.
26+
27+
Users should add the following `load()` statements to any `BUILD` or `.bzl`
28+
files that use these proto rules. Note that these require Protobuf v29.0 or
29+
higher.
30+
31+
```bazel
32+
load("@protobuf//bazel:proto_library.bzl", "proto_library")
33+
34+
load("@protobuf//bazel:cc_proto_library.bzl", "cc_proto_library")
35+
load("@protobuf//bazel:java_proto_library.bzl", "java_proto_library")
36+
load("@protobuf//bazel:java_lite_proto_library.bzl", "java_lite_proto_library")
37+
load("@protobuf//bazel:py_proto_library.bzl", "py_proto_library")
38+
```
39+
40+
### Stage 2
41+
42+
When Bazel 9 is released, the automatic loading of the protobuf library’s rules
43+
will be removed. At that point, you will need to have `load` statements in your
44+
Bazel build files.
45+
46+
### End Goal
47+
48+
Once the rules are in the protobuf repo, we intend to address common user
49+
requests, such as using prebuilts for the proto compiler where possible.

‎content/news/2024-10-02.md‎

Lines changed: 282 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,282 @@
1+
+++
2+
title = "Changes Announced on October 2, 2024"
3+
linkTitle = "October 2, 2024"
4+
toc_hide = "true"
5+
description = "Changes announced for Protocol Buffers on October 2, 2024."
6+
type = "docs"
7+
+++
8+
9+
The following sections cover planned breaking changes in the v30 release,
10+
expected in 2025 Q1. These describe changes as we anticipate them being
11+
implemented, but due to the flexible nature of software some of these changes
12+
may not land or may vary from how they are described in this topic.
13+
14+
## Changes in C++ {#cpp}
15+
16+
C++ will bump its major version from 5.29.x to 6.30.x.
17+
18+
### Descriptor APIs {#descriptor-apis}
19+
20+
v30 will update return types in descriptor (such as `full_name`) to be
21+
`absl::string_view`. This opens up memory savings in descriptors.
22+
23+
v28 introduced the `PROTOBUF_FUTURE_STRING_VIEW_RETURN_TYPE` macro, which you
24+
can use in the meantime to enable the updated return type ahead of the breaking
25+
release. The v30 release will flip the default and remove the macro.
26+
27+
### ctype Removed from FieldDescriptor Options {#ctype-removed}
28+
29+
v30 will stop exposing the `ctype` from `FieldDescriptor` options. You can use
30+
the `FieldDescriptor::cpp_string_type()` API, added in the
31+
[v28 release](https://github.com/protocolbuffers/protobuf/releases/tag/v28.0),
32+
in its place.
33+
34+
### Replace CMake Submodules with Fetched Deps {#replace-cmake-submods}
35+
36+
v30 will remove submodules and switches to upb's old CMake pattern of fetching
37+
dependencies.
38+
39+
If you use installed packages, you won't be affected. It could break some CMake
40+
workflows.
41+
42+
### Remove Deprecated APIs {#remove-deprecated}
43+
44+
v30 will remove the following public runtime APIs, which have been marked
45+
deprecated (such as `ABSL_DEPRECATED`) for at least one minor or major release
46+
and that are obsolete or replaced.
47+
48+
#### Arena::CreateMessage
49+
50+
**API:**
51+
[`Arena::CreateMessage`](https://github.com/protocolbuffers/protobuf/blob/f4b57b98b08aec8bc52e6a7b762edb7a1b9e8883/src/google/protobuf/arena.h#L179)
52+
53+
**Replacement:**
54+
[`Arena::Create`](https://github.com/protocolbuffers/protobuf/blob/f4b57b98b08aec8bc52e6a7b762edb7a1b9e8883/src/google/protobuf/arena.h#L191)
55+
56+
#### Arena::GetArena
57+
58+
**API:**
59+
[`Arena::GetArena`](https://github.com/protocolbuffers/protobuf/blob/237332ef92daf83a53e76decd6ac43c3fcee782b/src/google/protobuf/arena.h#L346)
60+
61+
**Replacement:** `value->GetArena()`
62+
63+
#### RepeatedPtrField::ClearedCount
64+
65+
**API:**
66+
[`RepeatedPtrField::ClearedCount`](https://github.com/protocolbuffers/protobuf/blame/f4b57b98b08aec8bc52e6a7b762edb7a1b9e8883/src/google/protobuf/repeated_ptr_field.h#L1157)
67+
68+
**Replacement:** Migrate to Arenas
69+
([migration guide](https://protobuf.dev/support/migration/#cleared-elements)).
70+
71+
#### JsonOptions
72+
73+
**API:**
74+
[`JsonOptions`](https://github.com/protocolbuffers/protobuf/blob/f4b57b98b08aec8bc52e6a7b762edb7a1b9e8883/src/google/protobuf/util/json_util.h#L22)
75+
76+
**Replacement:** `JsonPrintOptions`
77+
78+
### Dropping C++14 Support {#drop-cpp-14}
79+
80+
This release will drop C++ 14 as the minimum supported version and raise it to
81+
17, as per the
82+
[Foundational C++ Support matrix](https://github.com/google/oss-policies-info/blob/main/foundational-cxx-support-matrix.md).
83+
84+
Per [our policies](https://protobuf.dev/support/version-support/), we do not
85+
consider this to be a breaking change.
86+
87+
## Changes in JRuby {#jruby}
88+
89+
v30 will flip the default implementation for JRuby to FFI, which may be breaking
90+
for some JRuby users.
91+
92+
Note that this change doesn't create a Ruby major version bump because JRuby is
93+
[not officially supported](/support/version-support/#ruby).
94+
95+
## Changes in Python {#python}
96+
97+
Python will bump its major version from 5.29.x to 6.30.x.
98+
99+
### Dropping Python 3.8 Support
100+
101+
As per our official Python support policy, we will be dropping support for
102+
Python 3.8 and lower. This means the minimum supported Python version is 3.9.
103+
104+
### Remove bazel/system_python.bzl Alias {#python-remove-alias}
105+
106+
v30 will remove the legacy `bazel/system_python.bzl` alias.
107+
108+
Remove direct references to `system_python.bzl` in favor of using
109+
`protobuf_deps.bzl` instead. Use `python/dist/system_python.bzl` where it was
110+
moved
111+
[in v5.27.0](https://github.com/protocolbuffers/protobuf/commit/d7f032ad1596ceeabd45ca1354516c39b97b2551)
112+
if you need a direct reference.
113+
114+
### Field Setter Validation Changes {#python-setter-validation}
115+
116+
Python's and upb's field setters will be fixed in v30 to validate closed enums
117+
under edition 2023. Closed enum fields updated with invalid values will generate
118+
errors.
119+
120+
### Remove Deprecated APIs {#python-remove-apis}
121+
122+
v30 will remove the following public runtime APIs, which have been marked
123+
deprecated for at least one minor or major release and are obsolete or replaced.
124+
125+
#### Reflection Methods
126+
127+
**APIs:**
128+
[`reflection.ParseMessage`](https://github.com/protocolbuffers/protobuf/blob/7f395af40e86e00b892e812beb67a03564884756/python/google/protobuf/reflection.py#L40),
129+
[`reflection.MakeClass`](https://github.com/protocolbuffers/protobuf/blob/7f395af40e86e00b892e812beb67a03564884756/python/google/protobuf/reflection.py#L66)
130+
131+
**Replacement:** `message_factory.GetMessageClass()`
132+
133+
#### RPC Service Interfaces
134+
135+
**APIs:**
136+
[`service.RpcException`](https://github.com/protocolbuffers/protobuf/blob/21c545c8c5cec0b052dc7715b778f0353d37d02c/python/google/protobuf/service.py#L23),
137+
[`service.Service`](https://github.com/protocolbuffers/protobuf/blob/21c545c8c5cec0b052dc7715b778f0353d37d02c/python/google/protobuf/service.py#L28),
138+
[`service.RpcController`](https://github.com/protocolbuffers/protobuf/blob/21c545c8c5cec0b052dc7715b778f0353d37d02c/python/google/protobuf/service.py#L97),
139+
and
140+
[`service.RpcChannel`](https://github.com/protocolbuffers/protobuf/blob/21c545c8c5cec0b052dc7715b778f0353d37d02c/python/google/protobuf/service.py#L180)
141+
142+
**Replacement:** Starting with version 2.3.0, RPC implementations should not try
143+
to build on these, but should instead provide code generator plugins which
144+
generate code specific to the particular RPC implementation.
145+
146+
#### MessageFactory and SymbolDatabase Methods
147+
148+
**APIs:**
149+
[`MessageFactory.GetPrototype`](https://github.com/protocolbuffers/protobuf/blob/7f395af40e86e00b892e812beb67a03564884756/python/google/protobuf/message_factory.py#L145),
150+
[`MessageFactory.CreatePrototype`](https://github.com/protocolbuffers/protobuf/blob/7f395af40e86e00b892e812beb67a03564884756/python/google/protobuf/message_factory.py#L165),
151+
[`MessageFactory.GetMessages`](https://github.com/protocolbuffers/protobuf/blob/7f395af40e86e00b892e812beb67a03564884756/python/google/protobuf/message_factory.py#L185),
152+
[`SymbolDatabase.GetPrototype`](https://github.com/protocolbuffers/protobuf/blob/7f395af40e86e00b892e812beb67a03564884756/python/google/protobuf/symbol_database.py#L54),
153+
[`SymbolDatabase.CreatePrototype`](https://github.com/protocolbuffers/protobuf/blob/7f395af40e86e00b892e812beb67a03564884756/python/google/protobuf/symbol_database.py#L60),
154+
and
155+
[`SymbolDatabase.GetMessages`](https://github.com/protocolbuffers/protobuf/blob/7f395af40e86e00b892e812beb67a03564884756/python/google/protobuf/symbol_database.py#L66)
156+
157+
**Replacement:** `message_factory.GetMessageClass()` and
158+
`message_factory.GetMessageClassesForFiles()`.
159+
160+
## Changes in Objective-C {#objc}
161+
162+
**This will be the first breaking release for Objective-C**.
163+
164+
Objective-C will bump its major version from 3.x.x to 4.30.x.
165+
166+
### Overhaul Unknown Field Handling APIs Deprecating Most of the Existing APIs {#objc-field-handling}
167+
168+
v30 will deprecate `GPBUnknownFieldSet` and replace it with `GPBUnknownFields`.
169+
The new type will preserve the ordering of unknown fields from the original
170+
input or API calls, to ensure any semantic meaning to the ordering is maintained
171+
when a message is written back out.
172+
173+
As part of this, the `GPBUnknownField` type also has its APIs changed, with
174+
almost all of the existing APIs becoming deprecated and new ones added.
175+
176+
Deprecated property APIs:
177+
178+
* `varintList`
179+
* `fixed32List`
180+
* `fixed64List`
181+
* `lengthDelimitedList`
182+
* `groupList`
183+
184+
Deprecated modification APIs:
185+
186+
* `addVarint:`
187+
* `addFixed32:`
188+
* `addFixed64:`
189+
* `addLengthDelimited:`
190+
* `addGroup:`
191+
192+
Deprecated initializer `initWithNumber:`.
193+
194+
New property APIs:
195+
196+
* `type`
197+
* `varint`
198+
* `fixed32`
199+
* `fixed64`
200+
* `lengthDelimited`
201+
* `group`
202+
203+
This type will model a single field number in its value, rather than *grouping*
204+
all the values for a given field number. The APIs for creating new fields are
205+
the `add*` APIs on the `GPBUnknownFields` class.
206+
207+
v30 will also deprecate `-[GPBMessage unknownFields]`. In its place, there will
208+
be new APIs to extract and update the unknown fields of the message.
209+
210+
### Remove Deprecated APIs {#objc-remove-apis}
211+
212+
v30 will remove the following public runtime APIs, which have been marked
213+
deprecated for at least one minor or major release and are obsolete or replaced.
214+
215+
#### GPBFileDescriptor
216+
217+
**API:**
218+
[-[`GPBFileDescriptor` syntax]](https://github.com/protocolbuffers/protobuf/blob/44bd65b2d3c0470d91a23cc14df5ffb1ab0af7cd/objectivec/GPBDescriptor.h#L118-L119)
219+
220+
**Replacement:** Obsolete.
221+
222+
#### GPBMessage mergeFrom:extensionRegistry
223+
224+
**API:**
225+
[-[`GPBMessage mergeFrom:extensionRegistry:`]](https://github.com/protocolbuffers/protobuf/blob/44bd65b2d3c0470d91a23cc14df5ffb1ab0af7cd/objectivec/GPBMessage.h#L258-L261)
226+
227+
**Replacement:**
228+
[-[`GPBMessage mergeFrom:extensionRegistry:error:`]](https://github.com/protocolbuffers/protobuf/blob/44bd65b2d3c0470d91a23cc14df5ffb1ab0af7cd/objectivec/GPBMessage.h#L275-L277)
229+
230+
#### GPBDuration timeIntervalSince1970
231+
232+
**API:**
233+
[-[`GPBDuration timeIntervalSince1970`]](https://github.com/protocolbuffers/protobuf/blob/29fca8a64b62491fb0a2ce61878e70eda88dde98/objectivec/GPBWellKnownTypes.h#L95-L100)
234+
235+
**Replacement:**
236+
[-[`GPBDuration timeInterval`]](https://github.com/protocolbuffers/protobuf/blob/29fca8a64b62491fb0a2ce61878e70eda88dde98/objectivec/GPBWellKnownTypes.h#L74-L89)
237+
238+
#### GPBTextFormatForUnknownFieldSet
239+
240+
**API:**
241+
[`GPBTextFormatForUnknownFieldSet()`](https://github.com/protocolbuffers/protobuf/blob/29fca8a64b62491fb0a2ce61878e70eda88dde98/objectivec/GPBUtilities.h#L32-L43)
242+
243+
**Replacement:** Obsolete - Use
244+
[`GPBTextFormatForMessage()`](https://github.com/protocolbuffers/protobuf/blob/29fca8a64b62491fb0a2ce61878e70eda88dde98/objectivec/GPBUtilities.h#L20-L30),
245+
which includes any unknown fields.
246+
247+
#### GPBUnknownFieldSet
248+
249+
**API:**
250+
[`GPBUnknownFieldSet`](https://github.com/protocolbuffers/protobuf/blob/224573d66a0cc958c76cb43d8b2eb3aa7cdb89f2/objectivec/GPBUnknownFieldSet.h)
251+
252+
**Replacement:**
253+
[`GPBUnknownFields`](https://github.com/protocolbuffers/protobuf/blob/224573d66a0cc958c76cb43d8b2eb3aa7cdb89f2/objectivec/GPBUnknownFields.h)
254+
255+
#### GPBMessage unknownFields
256+
257+
**API:**
258+
[`GPBMessage unknownFields` property](https://github.com/protocolbuffers/protobuf/blob/224573d66a0cc958c76cb43d8b2eb3aa7cdb89f2/objectivec/GPBMessage.h#L73-L76)
259+
260+
**Replacement:**
261+
[-[`GPBUnknownFields initFromMessage:`]](https://github.com/protocolbuffers/protobuf/blob/224573d66a0cc958c76cb43d8b2eb3aa7cdb89f2/objectivec/GPBUnknownFields.h#L30-L38),
262+
[-[`GPBMessage mergeUnknownFields:extensionRegistry:error:`]](https://github.com/protocolbuffers/protobuf/blob/f26bdff7cc0bb7e8ed88253ba16f81614a26cf16/objectivec/GPBMessage.h#L506-L528),
263+
and
264+
[-[`GPBMessage clearUnknownFields`]](https://github.com/protocolbuffers/protobuf/blob/224573d66a0cc958c76cb43d8b2eb3aa7cdb89f2/objectivec/GPBMessage.h#L497-L504C9)
265+
266+
## Other Changes {#non-breaking}
267+
268+
In addition to those breaking changes are some other changes worth noting. While
269+
the following are not considered breaking changes, they may still impact users.
270+
271+
### Poison Pill Warnings {#poison}
272+
273+
v30 will update poison pills to emit warnings for old gencode + new runtime
274+
combinations that work under the new rolling upgrade policy, but will break in
275+
the *next* major bump. For example, Java 4.x.x gencode should work against 5.x.x
276+
runtime but warn of upcoming breakage against 6.x.x runtime.
277+
278+
### Changes to UTF-8 Enforcement in C# and Ruby {#utf-8-enforcement}
279+
280+
v30 will includes a fix to make UTF-8 enforcement consistent across languages.
281+
Users with bad non-UTF8 data in string fields may see surfaced UTF-8 enforcement
282+
errors earlier.

‎content/news/_index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,10 @@ New news topics will also be published to the
2020
The following news topics provide information in the reverse order in which it
2121
was released.
2222

23+
* [October 2, 2024](/news/2024-10-02) - Breaking
24+
changes in the upcoming 30.x release
25+
* [October 1, 2024](/news/2024-10-01) - Changes to
26+
Bazel builds
2327
* [June 26, 2024](/news/2024-06-26) - Dropping support
2428
for building Protobuf Java from source with Maven
2529
* [February 27, 2024](/news/2024-02-27) - Dropping
@@ -80,6 +84,7 @@ release notes will be more complete. Also, not everything from the chronological
8084
listing will be in these topics, as some content is not specific to a particular
8185
release.
8286

87+
* [Version 29.x](/news/v29)
8388
* [Version 26.x](/news/v26)
8489
* [Version 25.x](/news/v25)
8590
* [Version 24.x](/news/v24)

0 commit comments

Comments
 (0)