Skip to content

Commit b703d93

Browse files
Protocol Buffer TeamLogofile
Protocol Buffer Team
authored and
Logofile
committed
This documentation changes includes the following:
* Updates the UI for the Version Support page to make it easier to read * Adds a new News entry about upcoming changes in v30 * Updates the proto-limits.md file to remove some applies-only-internally content * Updates the Edition 2023 spec to reflect that the edition entry in a schema file can use either single quotes or double quotes around the edition number. PiperOrigin-RevId: 694522500 Change-Id: I2a83525c545a6228c06ff0734bdcd19bbbe51f43
1 parent 28ec5c8 commit b703d93

File tree

7 files changed

+872
-1370
lines changed

7 files changed

+872
-1370
lines changed

‎content/includes/version-tables.css‎

Lines changed: 117 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,4 +31,120 @@ tbody td.gray {
3131

3232
tbody td.yellow {
3333
background: #fff2cc;
34-
}
34+
}
35+
36+
/* version-table */
37+
38+
table.version-table tr.end-of-life th {
39+
background: #f4cccc;
40+
}
41+
table.version-table tr.internal-support th {
42+
background: #fce5cd;
43+
}
44+
table.version-table tr.maintenance th {
45+
background: #fff2cc;
46+
}
47+
table.version-table tr.active th {
48+
background: #d9ead3;
49+
text-decoration: underline;
50+
}
51+
table.version-table tr.future th {
52+
background: #fff;
53+
}
54+
table.version-table tr.future td {
55+
font-style: italic;
56+
}
57+
58+
table.version-table td:nth-child(4) {
59+
text-align: start;
60+
}
61+
62+
/* version-chart */
63+
64+
table.version-chart tr.end-of-life th {
65+
background: #f4cccc;
66+
}
67+
table.version-chart tr.internal-support th {
68+
background: #fce5cd;
69+
}
70+
table.version-chart tr.maintenance th {
71+
background: #fff2cc;
72+
}
73+
table.version-chart tr.active th {
74+
background: #d9ead3;
75+
text-decoration: underline;
76+
}
77+
table.version-chart tr.future th {
78+
background: #fff;
79+
}
80+
table.version-chart tr.future td {
81+
font-style: italic;
82+
}
83+
84+
table.version-chart td.internal-support {
85+
background: #fce5cd;
86+
}
87+
table.version-chart td.maintenance {
88+
background: #fff2cc;
89+
}
90+
table.version-chart td.active {
91+
background: #d9ead3;
92+
text-decoration: underline;
93+
}
94+
95+
/* latest release column */
96+
97+
/* visually replace 'yyQq' heading with string 'Latest' */
98+
table.version-chart th.latest-release span {
99+
display: none;
100+
}
101+
table.version-chart th.latest-release::after {
102+
content: "Latest"
103+
}
104+
105+
/* draw a focus rectangle around the latest release column */
106+
table.version-chart th.latest-release {
107+
border-top: 2px solid #e06666 !important;
108+
border-left: 2px solid #e06666 !important;
109+
border-right: 2px solid #e06666 !important;
110+
}
111+
table.version-chart td.latest-release {
112+
font-weight: bold;
113+
border-left: 2px solid #e06666 !important;
114+
border-right: 2px solid #e06666 !important;
115+
}
116+
table.version-chart tr:last-child td.latest-release {
117+
border-bottom: 2px solid #e06666 !important;
118+
}
119+
120+
/* future release columns */
121+
table.version-chart td:not(:has(~ .latest-release)):not(.latest-release) {
122+
font-style: italic;
123+
}
124+
125+
/* legend */
126+
127+
table.legend th {
128+
font-weight: normal;
129+
}
130+
131+
table.legend tr.end-of-life th {
132+
background: #f4cccc;
133+
}
134+
table.legend tr.internal-support th {
135+
background: #fce5cd;
136+
}
137+
table.legend tr.maintenance th {
138+
background: #fff2cc;
139+
}
140+
table.legend tr.active th {
141+
background: #d9ead3;
142+
text-decoration: underline;
143+
}
144+
table.legend tr.future th {
145+
background: #fff;
146+
}
147+
148+
table.legend td:nth-child(2) {
149+
text-align: start;
150+
}

‎content/news/2024-11-07.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
+++
2+
title = "Changes Announced on November 7, 2024"
3+
linkTitle = "November 7, 2024"
4+
toc_hide = "true"
5+
description = "Changes announced for Protocol Buffers on November 7, 2024."
6+
type = "docs"
7+
+++
8+
9+
The following sections cover planned breaking changes in the v30 release,
10+
expected in 2025 Q1. Also included are some changes that aren't breaking but may
11+
require action on your part. These are in addition to those mentioned in the
12+
[News article from October 2](/news/2024-10-02).
13+
14+
These describe changes as we anticipate them being implemented, but due to the
15+
flexible nature of software some of these changes may not land or may vary from
16+
how they are described in this topic.
17+
18+
## Introduce ASAN Poisoning After Clearing Oneof Messages on Arena
19+
20+
This change adds a hardening check that affects C++ protobufs using Arenas.
21+
Oneof messages allocated on the protobuf arena will now be cleared in debug and
22+
poisoned in ASAN mode. After calling clear, future attempts to use the memory
23+
region will cause a crash in ASAN as a use-after-free error.
24+
25+
This implementation
26+
[requires C++17](/news/2024-10-02#drop-cpp-14).
27+
28+
## Python setdefault Behavior Change for Map Fields
29+
30+
Starting in v30, `setdefault` will be similar to `dict` for `ScalarMap`, except
31+
that both key and value must be set. `setdefault` will be rejected for
32+
`MessageMaps`.
33+
34+
## Remove Deprecated py_proto_library Macro
35+
36+
The deprecated internal `py_proto_library` Bazel macro in `protobuf.bzl` will be
37+
removed in v30.x.
38+
39+
This should be replaced by the official `py_proto_library` which will be moved
40+
to protobuf in `bazel/py_proto_library` as of v29.x. This implementation was
41+
previously available in `rules_python` prior to v29.x.
42+
43+
## Python Nested Message Class \_\_qualname\_\_ Contains the Outer Message Name
44+
45+
Python nested message class `__qualname__` now contains the outer message name.
46+
Prior to v30, `__qualname__` has the same result with `__name__` for nested
47+
message, in that the outer message name was not included.
48+
49+
For example:
50+
51+
```python
52+
message Foo {
53+
message Bar {
54+
bool bool_field = 1;
55+
}
56+
}
57+
nested = test_pb2.Foo.Bar()
58+
self.assertEqual('Bar', nested.__class__.__name__)
59+
self.assertEqual('Foo.Bar', nested.__class__.__qualname__) # It was 'Bar' before
60+
```
61+
62+
## Dropping our C++ CocoaPods release
63+
64+
In v30, we will be dropping our C++ CocoaPods release, which has been broken
65+
since v4.x.x. C++ users should use our
66+
[GitHub release](https://github.com/protocolbuffers/protobuf/releases) directly
67+
instead.
68+
69+
## Ruby and PHP Errors in JSON Parsing
70+
71+
v30 fixes non-conformance in JSON parsing of strings in numeric fields per the
72+
[JSON spec](https://protobuf.dev/programming-guides/json/).
73+
74+
This fix will not be accompanied by a major version bump, but Ruby and PHP will
75+
now raise errors for non-numeric strings (e.g. "", "12abc", "abc") in numeric
76+
fields. v29.x will include a warning for these error cases.

‎content/news/_index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ 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+
* [November 7, 2024](/news/2024-11-07) - More breaking
24+
changes in the upcoming 30.x release
2325
* [October 2, 2024](/news/2024-10-02) - Breaking
2426
changes in the upcoming 30.x release
2527
* [October 1, 2024](/news/2024-10-01) - Changes to
@@ -84,6 +86,7 @@ release notes will be more complete. Also, not everything from the chronological
8486
listing will be in these topics, as some content is not specific to a particular
8587
release.
8688

89+
* [Version 30.x](/news/v30)
8790
* [Version 29.x](/news/v29)
8891
* [Version 26.x](/news/v26)
8992
* [Version 25.x](/news/v25)

‎content/news/v30.md‎

Lines changed: 62 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ The following announcements are specific to Version 30.x. For information
1010
presented chronologically, see [News](/news).
1111

1212
The following sections cover planned breaking changes in the v30 release,
13-
expected in 2025 Q1. These describe changes as we anticipate them being
13+
expected in 2025 Q1. Also included are some changes that aren't breaking but may
14+
require action on your part. These describe changes as we anticipate them being
1415
implemented, but due to the flexible nature of software some of these changes
1516
may not land or may vary from how they are described in this topic.
1617

@@ -84,9 +85,25 @@ This release will drop C++ 14 as the minimum supported version and raise it to
8485
17, as per the
8586
[Foundational C++ Support matrix](https://github.com/google/oss-policies-info/blob/main/foundational-cxx-support-matrix.md).
8687

87-
Per [our policies](https://protobuf.dev/support/version-support/), we do not
88+
Per [our policies](https://protobuf.dev/support/version-support), we do not
8889
consider this to be a breaking change.
8990

91+
## Introduce ASAN Poisoning After Clearing Oneof Messages on Arena
92+
93+
This change adds a hardening check that affects C++ protobufs using Arenas.
94+
Oneof messages allocated on the protobuf arena will now be cleared in debug and
95+
poisoned in ASAN mode. After calling clear, future attempts to use the memory
96+
region will cause a crash in ASAN as a use-after-free error.
97+
98+
This implementation requires C++17.
99+
100+
## Dropping our C++ CocoaPods release
101+
102+
In v30, we will be dropping our C++ CocoaPods release, which has been broken
103+
since v4.x.x. C++ users should use our
104+
[GitHub release](https://github.com/protocolbuffers/protobuf/releases) directly
105+
instead.
106+
90107
## Changes in JRuby {#jruby}
91108

92109
v30 will flip the default implementation for JRuby to FFI, which may be breaking
@@ -120,6 +137,15 @@ Python's and upb's field setters will be fixed in v30 to validate closed enums
120137
under edition 2023. Closed enum fields updated with invalid values will generate
121138
errors.
122139

140+
### Remove Deprecated py_proto_library Macro
141+
142+
The deprecated internal `py_proto_library` Bazel macro in `protobuf.bzl` will be
143+
removed in v30.x.
144+
145+
This should be replaced by the official `py_proto_library` which will be moved
146+
to protobuf in `bazel/py_proto_library` as of v29.x. This implementation was
147+
previously available in `rules_python` prior to v29.x.
148+
123149
### Remove Deprecated APIs {#python-remove-apis}
124150

125151
v30 will remove the following public runtime APIs, which have been marked
@@ -170,6 +196,31 @@ and
170196
No replacement. It's only in Python C++ which is no longer released. It is not
171197
supported in pure Python or UPB.
172198

199+
### Python setdefault Behavior Change for Map Fields
200+
201+
Starting in v30, `setdefault` will be similar to `dict` for `ScalarMap`, except
202+
that both key and value must be set. `setdefault` will be rejected for
203+
`MessageMaps`.
204+
205+
## Python Nested Message Class \_\_qualname\_\_ Contains the Outer Message Name
206+
207+
Python nested message class `__qualname__` now contains the outer message name.
208+
Prior to v30, `__qualname__` has the same result with `__name__` for nested
209+
message, in that the outer message name was not included.
210+
211+
For example:
212+
213+
```python
214+
message Foo {
215+
message Bar {
216+
bool bool_field = 1;
217+
}
218+
}
219+
nested = test_pb2.Foo.Bar()
220+
self.assertEqual('Bar', nested.__class__.__name__)
221+
self.assertEqual('Foo.Bar', nested.__class__.__qualname__) # It was 'Bar' before
222+
```
223+
173224
## Changes in Objective-C {#objc}
174225

175226
**This will be the first breaking release for Objective-C**.
@@ -324,3 +375,12 @@ runtime but warn of upcoming breakage against 6.x.x runtime.
324375
v30 will includes a fix to make UTF-8 enforcement consistent across languages.
325376
Users with bad non-UTF8 data in string fields may see surfaced UTF-8 enforcement
326377
errors earlier.
378+
379+
## Ruby and PHP Errors in JSON Parsing
380+
381+
v30 fixes non-conformance in JSON parsing of strings in numeric fields per the
382+
[JSON spec](https://protobuf.dev/programming-guides/json/).
383+
384+
This fix will not be accompanied by a major version bump, but Ruby and PHP will
385+
now raise errors for non-numeric strings (e.g. "", "12abc", "abc") in numeric
386+
fields. v29.x will include a warning for these error cases.

‎content/programming-guides/proto-limits.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,9 @@ specs.
3333

3434
## Number of Values in an Enum {#enum}
3535

36-
The lowest limit is ~1700 values, in Java (fix available
37-
go/java-large-enum-support). Other languages have different limits.
36+
The lowest limit is ~1700 values, in Java
37+
. Other languages have different
38+
limits.
3839

3940
## Total Size of the Message {#total}
4041

‎content/reference/protobuf/edition-2023-spec.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@ The edition statement replaces the legacy `syntax` keyword, and is used to
105105
define the edition that this file is using.
106106

107107
```
108-
edition = "edition" "=" ("'" decimalLit '"') ";"
108+
edition = "edition" "=" [ ( "'" decimalLit "'" ) | ( '"' decimalLit '"' ) ] ";"
109109
```
110110

111111
## Import Statement {#import_statement}

0 commit comments

Comments
 (0)