This change includes the following:

* Reverts changes made in the GitHub Actions workflow
* Adds a paragraph to the News topic about upcoming plans to announce changes to the protobuf mailing list
* Adds information to the Proto2 topic about the system checking UTF-8 validity in String fields
* Adds information to the Proto3 topic about a symbol `FooEntry` not being compatible with a map `foo` in the same scope
* Clarifies and corrects information about what is generated in Dart for  enums
* Adds extensive new information to the Cross-Version Runtime Guarantee topic
* Adds information to the Version Support topic about an extension to support for Java 3.25.x

PiperOrigin-RevId: 629749655
Change-Id: I1b7cf99abb2aa454b9ccedb98fb45268b127ceb1

Author: Protocol Buffer Team

.github/workflows/gh-pages.yml

@@ -1,5 +1,4 @@
 name: github pages
-
 on:
   push:
     branches:
@@ -13,17 +12,13 @@ jobs:
   deploy:
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v3
         with:
           submodules: true  # Fetch Hugo themes (true OR recursive)
           fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
 
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
       - name: Setup Hugo
-        uses: peaceiris/actions-hugo@v3
+        uses: peaceiris/actions-hugo@v2
         with:
           hugo-version: 'latest'
           extended: true
@@ -35,9 +30,9 @@ jobs:
         run: hugo --minify
 
       - name: Deploy
-        uses: peaceiris/actions-gh-pages@v4
+        uses: peaceiris/actions-gh-pages@v3
         if: github.ref == 'refs/heads/main'
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./public
-          cname: protobuf.dev
+          cname: protobuf.dev

content/news/_index.md

@@ -11,6 +11,10 @@ Buffers, and plans for upcoming changes. The information is available both
 chronologically and per-release. Note that not everything is included in the
 per-release topics, as some content is not tied to a version.
 
+New news topics will also be published to the
+[protobuf@](https://groups.google.com/g/protobuf) mailing list under the subject
+\[Announcement\].
+
 ## Chronological {#chronological}
 
 The following news topics provide information in the reverse order in which it

content/programming-guides/proto2.md

@@ -462,7 +462,7 @@ automatically generated class:
       </tr>
       <tr>
         <td>string</td>
-        <td>A string must always contain UTF-8 encoded or 7-bit ASCII text, and
+        <td>A string must always contain UTF-8 encoded<sup>[5]</sup> or 7-bit ASCII text, and
         cannot be longer than 2<sup>32</sup>.</td>
         <td>string</td>
         <td>String</td>
@@ -502,6 +502,10 @@ checking to make sure it is valid.
 when decoded, but can be an int if an int is given when setting the field. In
 all cases, the value must fit in the type represented when set. See [2].
 
+<sup>[5]</sup> Proto2 typically doesn't ever check the UTF-8 validity of string
+fields. Behavior varies between languages though, and invalid UTF-8 data should
+not be stored in string fields.
+
 You can find out more about how these types are encoded when you serialize your
 message in
 [Protocol Buffer Encoding](/programming-guides/encoding).

content/programming-guides/proto3.md

@@ -1076,6 +1076,8 @@ map<string, Project> projects = 3;
     field is serialized is language-dependent. In C++, Java, Kotlin, and Python
     the default value for the type is serialized, while in other languages
     nothing is serialized.
+*   No symbol `FooEntry` can exist in the same scope as a map `foo`, because
+    `FooEntry` is already used by the implementation of the map.
 
 The generated map API is currently available for all supported languages. You
 can find out more about the map API for your chosen language in the relevant

content/reference/dart/dart-generated.md

@@ -347,8 +347,19 @@ enum Color {
 
 The protocol buffer compiler will generate a class called `Color`, which extends
 the `ProtobufEnum` class. The class will include a `static const Color` for each
-of the three values defined as well as a `static const List<Color>` containing
-all the three non-unspecified values. It will also include the following method:
+of the four values, as well as a `static const List<Color>` that contains the
+values.
+
+```dart
+static const List<Color> values = <Color> [
+  COLOR_UNSPECIFIED,
+  COLOR_RED,
+  COLOR_GREEN,
+  COLOR_BLUE,
+];
+```
+
+It will also include the following method:
 
 -   `static Color? valueOf(int value)`: Returns the `Color` corresponding to the
     given numeric value.

content/support/cross-version-runtime-guarantee.md

@@ -12,27 +12,49 @@ produced from `protoc`) and the runtime libraries that must be included when
 using the generated code. When these come from different releases of protobuf,
 we are in a "cross version runtime" situation.
 
-Historically, protobuf has not documented its cross-version runtime
-compatibility guarantees and has been inconsistent about enforcing what
-guarantees it provides. Moving forward, we intend to offer the following
-guarantees across all languages except C++. These are the default guarantees;
-however, owners of protobuf code generators and runtimes may explicitly override
-them with more specific guarantees for that language.
+We intend to offer the following guarantees across all languages except
+[C++](#cpp). These are the default guarantees; however, owners of protobuf code
+generators and runtimes may explicitly override them with more specific
+guarantees for that language.
+
+Protobuf cross-version usages outside the guarantees are **error-prone and not
+supported**. Version skews can lead to *flakes and undefined behaviors* that are
+hard to diagnose, even if it can often *seem* to work as long as nothing has
+changed in a source-incompatible way. For Protobuf, the proliferation of tools
+and services that rely on using unsupported Protobuf language bindings prevents
+the protobuf team from updating the protobuf implementation in response to bug
+reports or security vulnerabilities.
+
+## New Gencode + Old Runtime = Never Allowed {#backwards}
+
+We may add new runtime APIs in any kind of release (Major, Minor, or Patch).
+Gencode in that release is allowed to use those new APIs. The consequence is
+that gencode should never be paired with a runtime that predates the `protoc`
+and plugin that was used to generate those bindings.
+
+We will add “poison pills” where possible to prevent attempts to pair newer
+gencode with an older runtime.
 
 ## Major Versions {#major}
 
-Protobuf will not support mixing generated code and runtimes across major
-version boundaries. We will add “poison pills” where possible to detect these
-mismatches.
+Starting with the 2025Q1 release, the protobuf project will adopt a rolling
+compatibility window for major versions. Code generated for a major version V
+(full version: V.x.y) will be supported by protobuf runtimes of version V and
+V+1.
+
+Protobuf will not support using gencode from version V with runtime >= V+2
+and will be using a "poison pill" mechanism to fail with a clear error message
+when a software assembly attempts to use such a configuration.
 
 ## Minor Versions {#minor}
 
 Within a single major runtime version, generated code from an older version of
 `protoc` will run on a newer runtime.
 
-Within a single major runtime version, generated code from a newer version of
-`protoc` is not guaranteed to run on an older runtime. We will add “poison
-pills” where possible to detect these mismatches.
+## Cross-domain {#cross-domain}
+
+Mixing Protobuf gencode and runtime across the boundary between open source and
+Google-internal will not be supported.
 
 ## Security Exception {#exception}
 

content/support/version-support.md

@@ -496,7 +496,7 @@ This table provides specific dates for support duration.
   <tr>
     <td class="gray">3.25.x</td>
     <td>1 Nov 2023</td>
-    <td>31 Mar 2025</td>
+    <td>31 Mar 2026*</td>
   </tr>
   <tr>
     <td class="gray">4.26.x</td>
@@ -505,6 +505,12 @@ This table provides specific dates for support duration.
   </tr>
 </table>
 
+**NOTE:** the support window for the Java 3.25.x release will be 24 months
+rather than the typical 12 months for the final release in a major version line.
+Future major version updates (5.x+) will adopt an improved
+["rolling compatibility window"](/support/cross-version-runtime-guarantee/#major)
+that should allow a return to 12-month support windows.
+
 This table graphically shows support durations.
 
 Java will target making major version bumps annually in Q1 of each year.
@@ -567,13 +573,14 @@ Java will target making major version bumps annually in Q1 of each year.
     <td class="gray">3.25.x</td>
     <td title=23Q2></td>
     <td title=23Q3></td>
+<!--3.25.x is special and will be publicly supported until end of 26Q1-->
     <td title=23Q4 class="blue">IR</td>
     <td title=24Q1 class="green">PS</td>
     <td title=24Q2 class="green">PS</td>
     <td title=24Q3 class="green">PS</td>
     <td title=24Q4 class="green">PS</td>
     <td title=25Q1 class="green">PS</td>
-    <td title=25Q2 class="red">SE</td>
+    <td title=25Q2 class="green">PS</td>
   </tr>
   <tr>
     <td class="gray">26.x</td>
@@ -597,7 +604,7 @@ Java will target making major version bumps annually in Q1 of each year.
   </tr>
   <tr>
     <td class="gray">27.x</td>
-    <td class="gray"></td>
+    <td class="gray">4.27.x</td>
     <td title=23Q2></td>
     <td title=23Q3></td>
     <td title=23Q4></td>
@@ -610,7 +617,7 @@ Java will target making major version bumps annually in Q1 of each year.
   </tr>
   <tr>
     <td class="gray">28.x</td>
-    <td class="gray"></td>
+    <td class="gray">4.28.x</td>
     <td title=23Q2></td>
     <td title=23Q3></td>
     <td title=23Q4></td>
@@ -621,6 +628,32 @@ Java will target making major version bumps annually in Q1 of each year.
     <td title=25Q1></td>
     <td title=25Q2></td>
   </tr>
+  <tr>
+    <td class="gray">29.x</td>
+    <td class="gray">4.29.x</td>
+    <td title=23Q2></td>
+    <td title=23Q3></td>
+    <td title=23Q4></td>
+    <td title=24Q1></td>
+    <td title=24Q2></td>
+    <td title=24Q3></td>
+    <td title=24Q4 class="blue">IR</td>
+    <td title=25Q1></td>
+    <td title=25Q2></td>
+  </tr>
+  <tr>
+    <td class="gray">30.x</td>
+    <td class="gray">5.30.x</td>
+    <td title=23Q2></td>
+    <td title=23Q3></td>
+    <td title=23Q4></td>
+    <td title=24Q1></td>
+    <td title=24Q2></td>
+    <td title=24Q3></td>
+    <td title=24Q4></td>
+    <td title=25Q1 class="blue">IR</td>
+    <td title=25Q2></td>
+  </tr>
 </table>
 
 <table>