Nachrichtenankündigungen für Version 26.x

Änderungen für Protocol Buffers Version 26.x angekündigt.

Die folgenden Ankündigungen sind spezifisch für Version 26.x, die am 13. März 2024 veröffentlicht wurde. Informationen, die chronologisch dargestellt sind, finden Sie unter Nachrichten.

Allgemeine Änderungen

Änderungen an JSON-Formatter-Optionen

Ab der 26.x-Linie wird die JSON-Formatter-Option zum Drucken von Feldern mit Standardwerten durch eine feste Methode zur konsistenten Behandlung von proto2 und proto3 optional Feldern ersetzt.

  • Java: includingDefaultValueFields() wird durch alwaysPrintFieldsWithNoPresence() ersetzt.
  • C++: always_print_default_values wird durch always_print_fields_with_no_presence=True ersetzt.
  • Py: including_default_value_fields=True wird durch always_print_fields_with_no_presence=True ersetzt.

Das neue Flag verhält sich bei proto3-Nachrichten identisch zum alten Flag, gilt aber nicht mehr für proto2 optional Felder. Die alten Flags galten für proto2 optional Felder, aber nicht für proto3 optional Felder.

Poison Pilling von Gencode / Laufzeitkonflikten

Gemäß unserer Cross-Version Runtime Guarantees unterstützt Protobuf nicht das Mischen von generiertem Code und Laufzeiten über Hauptversionsgrenzen hinweg, oder das Mischen von generiertem Code einer neueren Version von protoc mit älteren Laufzeiten innerhalb einer einzelnen Hauptlaufzeitversion. Wir planen, „Poison Pills“ einzuführen, um diese nicht erlaubten Abweichungen zu erkennen und durchzusetzen.

Dies wird nicht als breaking change betrachtet, da es lediglich die Durchsetzung bestehender Richtlinien hinzufügt, kann aber erfordern, dass Benutzer ihren generierten Code aktualisieren.

C++ Breaking Changes

In v26 planen wir einen Major-Versionssprung für C++ gemäß unserer Breaking Changes Policy und Version Support Policy.

Die folgenden Abschnitte beschreiben die Liste der Breaking Changes, die wir in der Version 26.0 von Protocol Buffers planen. Beachten Sie, dass Pläne sich ändern können und werden. Dies sind potenzielle Breaking Changes, über die Sie sich bewusst sein sollten, aber sie könnten in dieser bestimmten Version nicht stattfinden oder gar nicht.

Entfernen von veralteten clear-APIs für wiederholte Felder

Die folgenden veralteten Methoden werden entfernt

  • RepeatedPtrField::ReleaseCleared()
  • RepeatedPtrField::ClearedCount()
  • RepeatedPtrField::AddCleared()

Entfernen von veralteten C++ Legacy-Syntax-Deskriptor-APIs

Mit der Veröffentlichung von Editions wird die Syntax nicht mehr für die Geschäftslogik unterstützt. Verwenden Sie stattdessen die verschiedenen Feature-Helfer in descriptor.h, um gezieltere Verhaltensweisen abzufragen, wie z. B. has_presence, um Features in C++ abzufragen.

Entfernen von veralteten Syntax-Accessoren

Wir planen, den veralteten Syntax-Accessor, FileDescriptor::Syntax, in v26 zu entfernen. Wir empfehlen stattdessen die Getter von FileDescriptor::edition zu verwenden.

Entfernen der veralteten Methode SupportsUnknownEnumValues

Die Methode SupportsUnknownEnumValues wurde im März 2023 als veraltet markiert. Wir planen, sie in v26 zu entfernen.

Entfernen von std::string-Fehlersammler-Überschreibungen

Wir planen, die veralteten std::string-Methoden in Fehlersammlern zu entfernen.

Java Breaking Changes

In v26 planen wir einen Major-Versionssprung für Java gemäß unserer Breaking Changes Policy und Version Support Policy.

Die folgenden Abschnitte beschreiben die Liste der Breaking Changes, die wir in der Version 26.0 von Protocol Buffers planen. Beachten Sie, dass Pläne sich ändern können und werden. Dies sind potenzielle Breaking Changes, über die Sie sich bewusst sein sollten, aber sie könnten in dieser bestimmten Version nicht stattfinden oder gar nicht.

Brechen der Kompatibilität mit altem generiertem Code

v26.x wird die Kompatibilität mit generiertem Code aus älteren Hauptversionen brechen. Benutzer sollten alten generierten Code neu generieren, damit er von der gleichen Version stammt.

Beispielsweise wird GeneratedMessageV3, das ursprünglich zur Abwärtskompatibilität mit generiertem Code von v2.x.x gegen v3.x.x Laufzeit eingeführt wurde, in GeneratedMessage umbenannt. Laufzeiten werden aktualisiert, um Editions zu unterstützen, die nicht mit altem generiertem Code kompatibel sein werden.

Dies steht im Einklang mit unseren bestehenden Cross-Version Runtime Guarantees und ist eine breaking change.

Entfernen von veralteten Methoden/Variablen

v26.x entfernt den Zugriff auf veraltete Methoden und Variablen. Diese wurden in einer früheren Version bereits als @Deprecated markiert.

Dadurch wird der Zugriff auf die folgende nicht erschöpfende Liste entfernt:

  • Descriptor-Syntax-APIs, die durch entsprechende Feature-Accessor ersetzt werden sollten (z. B. FieldDescriptor.hasPresence(), EnumDescriptor.isClosed())

  • TextFormat-Druckmethoden, die durch entsprechende TextFormat.printer()-Methoden ersetzt werden sollten.

  • PARSER-Variable, die durch die Methode parser() ersetzt werden sollte.

  • Laufzeitmethoden für die Kompatibilität mit altem v2.x.x Gencode. Dies wird gemäß unseren Cross Version Runtime Guarantees nicht mehr unterstützt.

Weitere Details werden in den entsprechenden Release Notes verfügbar sein.

PHP Breaking Changes

Die folgenden Änderungen sind für die 26.x-Linie geplant

  • UTF-8-Validierung für String-Felder in Settern.
  • Entfernen von generischen Diensten. (Commit 40ad3fa)

Python Breaking Changes

In v26 planen wir einen Major-Versionssprung für Python gemäß unserer Breaking Changes Policy und Version Support Policy.

Die folgenden Änderungen sind für die 26.x-Linie geplant

  • str(msg) soll ungültiges UTF-8 in String-Feldern escapen.
  • text_format.MessageToString() soll standardmäßig rohes UTF-8 ausgeben und dabei ungültige UTF-8-Sequenzen escapen.
  • Beheben von Zeitstempel-Grenzwerten (Commit 1250d5f)

Entfernen von veralteten APIs

In der 26.x-Version werden die folgenden veralteten APIs entfernt:

Ablehnen von Extend Repeated Field mit None Iterable

Ab der 26.x-Version wird das Erweitern von wiederholten Feldern mit einem None-Iterable abgelehnt (es wird ein TypeError ausgelöst). Zum Beispiel wird m.repeated_int32.extend(None) abgelehnt.

Entfernen von RegisterExtension in der Nachrichtenklasse

Ab der 26.x-Version wird RegisterExtension entfernt. Sie können Erweiterungen in Python über die Eigenschaft Extensions von Nachrichtenobjekten abrufen.

Dies betrifft sowohl reines Python als auch die C++-Implementierung von Python, aber nicht upb Python.

Entfernen der Unterstützung für setup.py und setup.cfg von GitHub

In der 26.x-Version werden setup.py und setup.cfg nicht mehr im Verzeichnis python/ des GitHub-Repositorys oder in GitHub Release Tarballs vorhanden sein. Das bedeutet, dass es nicht mehr möglich sein wird, ein Python-Paket direkt aus dem GitHub-Repository oder einem Release Tarball zu erstellen.

Die Python-Quellpakete, die auf PyPI veröffentlicht werden, enthalten weiterhin eine setup.py im obersten Verzeichnis. Dies ist die unterstützte und empfohlene Methode zum Erstellen von Python-Binärpaketen für Benutzer, die die von uns auf PyPI verteilten Binärpakete nicht verwenden möchten.

Weitere Informationen finden Sie unter #15671.

Zeitstempel werden auf Gültigkeit geprüft

In v26 wird das System prüfen, ob Timestamp-Werte gültig sind. Sekunden müssen im Bereich [-62135596800, 253402300799] und Nanos im Bereich [0, 999999999] liegen. Werte außerhalb dieser Bereiche lösen eine Ausnahme aus.

Entfernen von veralteten Syntax-Accessoren

Wir planen, den veralteten Syntax-Accessor, FileDescriptor.syntax, in v26 zu entfernen. Wir planen, FileDescriptor.edition an seiner Stelle hinzuzufügen.

Entfernung der Unterstützung für UnknownFields

In v25 wurde message.UnknownFields() in reinem Python und C++-Erweiterungen als veraltet markiert. Wir planen, es in v26 zu entfernen. Verwenden Sie die neue Unterstützung für UnknownFieldSet(message) in unknown_fields.py als Ersatz.

Weitere Details zu all diesen Änderungen finden Sie in den entsprechenden Release Notes.

Ruby Breaking Changes

  • Behebt RepeatedField#each_index, um die korrekte Semantik zu haben. (#11767)
  • Entfernt die Ruby DSL und den zugehörigen Kompatibilitätscode, wodurch die im April angekündigte Migration abgeschlossen wird.
  • Korrekturen bei Message#to_h
    • Entfernt nicht gesetzte Oneof-Felder. (#6167)
    • Entfernt nicht gesetzte Sub-Nachrichtenfelder
  • Verwendet den Pool der Nachricht für encode_json/decode_json.
  • Entfernt den veralteten Syntax-Accessor, FileDescriptor.syntax und fügt stattdessen semantische Prüfungen hinzu.
    • FieldDescriptor.has_presence zum Testen, ob ein Feld Präsenz hat.
    • FieldDescriptor.is_packed zum Testen, ob ein wiederholtes Feld gepackt ist.
    • FieldDescriptor.requires_utf8_validation zum Testen, ob ein String-Feld eine UTF-8-Validierung erfordert.
    • EnumDescriptor.is_closed zum Testen, ob ein Enum geschlossen ist.

Freeze ist jetzt rekursiv in Ruby

Ab der 26.x-Linie wird bei Anwendung von freeze diese rekursiv angewendet und betrifft alle Sub-Nachrichten, Maps und wiederholten Felder.

upb Breaking Changes

Die folgenden Änderungen sind für die 26.x-Linie geplant