Zum Inhalt springen
DuckDBDuckDBDuckDB
Deutsch

Release-Zyklus

Dieses Dokument beschreibt den Release-Zyklus von DuckDB und den Core-Erweiterungen. Es richtet sich an Entwickler, die an DuckDB-Erweiterungen arbeiten, und soll die zugrunde liegenden Abläufe verständlicher machen.

Überblick

  • DuckDB folgt Semantic Versioning (v<MAJOR>.<MINOR>.<PATCH>)
  • Minor-Versionen erscheinen etwa alle 4 Monate
  • Patch-Releases werden bei Bedarf herausgegeben für:
    • Die aktuelle stabile Version
    • Die aktuelle Long-Term-Support-Version (LTS)
  • Alle Releases sind im Release-Kalender aufgeführt

Terminologie

In den Release-Dokumenten verwenden wir einige grundlegende Begriffe für Versionen und Branches. Wir gehen hier kurz darauf ein.

  • vx.y.z: Das aktuelle stabile Release
  • vx.y-codename: Der Name des Branches, aus dem vx.y.<n>-Releases entstehen
  • vx.<y+1>-codename: Der Branch-Name, der für den Branch verwendet wird, aus dem das nächste Minor-Release entsteht
  • Main release cycle: Die Branches, Commits und PRs, die zu vx.<y+1>.0- und vx.y.<z+1>-Releases führen
  • Active branch: Ein Branch, der Teil des Haupt-Release-Zyklus ist. Entweder main oder vx.<y+n>-codename mit n >= 0
  • Single branch extension: Erweiterung mit 1 aktivem Branch. Da main immer ein aktiver Branch ist, ist das immer main. Das bedeutet, alle anderen Branches der Form vx.y-codename müssen vx.<y-n>-codename mit n >= 1 sein
  • Multi branch extension: Erweiterung mit mehr als 1 aktivem Branch
  • Two branch extension: Erweiterung mit zwei aktiven Branches: main und vx.y-codename
  • Three branch extension: Erweiterung mit drei aktiven Branches: main, vx.y-codename und vx.<y+1>-codename
  • LTS release: Long-Term-Support-Release. Diese Releases erhalten Unterstützung (Patch-Releases) über ihre Lebensdauer im aktiven Release-Zyklus hinaus. Derzeit erhalten LTS-Releases 1 Jahr Unterstützung
  • Unstable API extension: Eine Erweiterung, die auf die unstable Extension-API zielt. Das kann sowohl die C++-API als auch die unstable C-API sein. Diese Erweiterungen sind über mehrere DuckDB-Versionen hinweg nicht binärkompatibel
  • Stable API extension: Eine Erweiterung, die auf die stable C-API von DuckDB zielt. Diese Erweiterungen sind über mehrere DuckDB-Versionen hinweg binärkompatibel
  • In-tree extensions: Erweiterungen, die im Quellbaum von duckdb/duckdb liegen

Haupt-Branches und Tags

In der git-basierten Versionsverwaltung dienen Branches dazu, mehrere Versionen derselben Codebasis parallel zu halten. Bei DuckDB gibt es zwei Kern-Branches, die die Hauptrolle im Release-Zyklus von DuckDB (und den Erweiterungen) spielen. Zuerst listen wir das Format dieser Kern-Branches auf.

  • main-Branch: Der Main-Branch kann Verschiedenes bedeuten, gilt aber allgemein als Auffang-Branch
  • vx.y-codename-Branch: Der Branch, aus dem alle vx.y.z-Releases entstehen
  • vx.y.z-Tag: Ein stabiles DuckDB-Release. Diese Tags sind schreibgeschützt und bleiben immer an denselben Commit gebunden

Der Haupt-Release-Zyklus von DuckDB

LTS-Releases (Long-Term Support) folgen einem eigenen Wartungszyklus, um längere Unterstützung und Stabilität zu bieten.

Der Haupt-Release-Zyklus von DuckDB besteht aus 3 Phasen: Mid-cycle, Pre-release und Feature freeze. Diese Phasen sind klar definiert und werden kommuniziert, damit das gesamte Team synchron auf das nächste Release hinarbeitet.

Phase 1: Mid-cycle

Aktive DuckDB-Branches

  • main
  • vx.y-codename

Beschreibung

Die Phase Mid-cycle ist die häufigste Phase des Release-Zyklus; etwa 75 % der Zeit wird in dieser Phase verbracht. Sie entspricht dem Normalbetrieb: Das kommende Release liegt noch weit entfernt, und das Team arbeitet intensiv daran, vielfältige Features und Bugfixes einzupflegen. In dieser Phase können Patch-Releases (vx.y.<z+n>) aus dem Branch vx.y-codename entstehen. Die Patches werden in den Branch vx.y-codename gemergt, und der Branch vx.y-codename wird häufig in main gemergt, damit beide synchron bleiben.

PRs in DuckDB

  • Bugfixes für vx.y.<z+n>-Patch-Releases werden in vx.y-codename gemergt
  • Features und Bugfixes für vx.<y+1>.0 werden in main gemergt

Phase 2: Pre-release

Aktive Branches

  • main
  • vx.y-codename
  • vx.<y+1>-codename

Beschreibung

Die Pre-release-Phase dient der Vorbereitung des kommenden Minor-Releases vx.<y+1>.0. Zu Beginn dieser Phase wird der Branch vx.<y+1>-codename angelegt. Dieser Branch dient dem kommenden Minor-Release und ist der Branch, aus dem alle nachfolgenden Patch-Releases vx.<y+1>.<n> erscheinen.

PRs in DuckDB

  • Bugfixes für vx.y.<z+1>-Patch-Releases werden in vx.y-codename gemergt
  • Features und Bugfixes für vx.<y+1>.0 werden in vx.<y+1>-codename gemergt
  • Features für vx.<y+2>.0 werden in vx.<y+2>-codename gemergt

Phase 3: Feature Freeze

Aktive Branches

  • main
  • vx.y-codename
  • vx.<y+1>-codename

Beschreibung

Die Feature-Freeze-Phase liegt dem Release am nächsten. In dieser Phase dürfen Features nicht mehr in vx.<y+1>-codename gemergt werden; es werden nur noch Bugfixes gemergt. Ziel dieser Phase ist die Qualität des kommenden Releases. In dieser Phase werden zusätzliche Tests und Benchmarks durchgeführt, während das Risiko kurzfristig eingebrachter Bugs durch das Verbot von Feature-Merges sinkt.

PRs in DuckDB

  • Bugfixes für vx.y.<z+1> sind nicht mehr zulässig und sollten stattdessen vx.<y+1>.0 gelten
  • Bugfixes für vx.<y+1>.0 werden in vx.<y+1>-codename gemergt
  • Features für vx.<y+1>.0 sind nicht mehr zulässig und sollten stattdessen vx.<y+2>.0 gelten
  • Features für vx.<y+2>.0 werden in vx.<y+2>-codename gemergt

Haupt-Release-Zyklus der Erweiterungen

Die meisten DuckDB-Erweiterungen sind vollständig vom Haupt-Repository duckdb/duckdb getrennt und können ihren eigenen Release-Zyklus verfolgen. In diesem Abschnitt kategorisieren wir verschiedene Arten von DuckDB-Erweiterungen und gehen ihre Release-Zyklen durch.

Um den Release-Zyklus von Erweiterungen zu beschreiben, müssen wir Erweiterungen zunächst in drei Gruppen einteilen, da Erweiterungen denselben Release-Zyklus teilen, je nachdem, zu welcher dieser drei Kategorien sie gehören.

  • In-tree-Erweiterungen
  • Unstable-API-Erweiterungen
  • Stable-API-Erweiterungen

Wir gehen nun die Release-Zyklen der drei Kategorien in aufsteigender Komplexität durch.

In-tree-Erweiterungen

Bei In-tree-Erweiterungen ist der Release-Zyklus sehr einfach. Da ihr Code im Repository duckdb/duckdb liegt, laufen sie vollständig im Gleichschritt mit DuckDB. Das bedeutet dieselbe Versionierung und dieselben Branches. In diesem Sinne sind sie keine echten Erweiterungen, sondern eher nachladbare Teile der Codebasis duckdb/duckdb.

Stable-API-Erweiterungen

Stable-API-Erweiterungen sind in DuckDB ein vergleichsweise neues Konzept, sollen aber künftig die Mehrheit der Erweiterungen bilden. Stable-API-Erweiterungen basieren auf der stabilen C-Extension-API und sind damit mit mehreren DuckDB-Versionen binärkompatibel. Ihr Release-Zyklus kann bzw. sollte daher auch vollständig vom DuckDB-Release-Zyklus getrennt sein.

Der Release-Zyklus für Stable-API-Erweiterungen ist noch in Arbeit. Die Grundidee ist, dass der Release-Zyklus von Stable-API-Erweiterungen einem ähnlichen, aber eigenen Zyklus wie dem von duckdb/duckdb folgt, wobei jede Version eine oder mehrere DuckDB-Versionen als Ziel hat.

Unstable-API-Erweiterungen

Unstable-API-Erweiterungen machen derzeit die Mehrheit der DuckDB-Erweiterungen aus. Diese Erweiterungen zielen entweder auf die C++- Extension-API oder auf die unstable C-Extension-API. Aus Sicht des Release-Zyklus sind sie am komplexesten. Jede Version einer Unstable-API-Erweiterung zielt nur auf eine einzige DuckDB-Version. Diese 1:1-Kopplung bedeutet, dass der Release-Zyklus dieser Erweiterungen oft ein mitunter verflochtenes Zusammenspiel mit dem Haupt-Release-Zyklus von DuckDB bildet. Ziel ist es, möglichst viele Erweiterungen auf stabile APIs umzustellen; Unstable-API-Erweiterungen werden aber noch länger existieren, sodass ihr Lebenszyklus klar definiert bleiben muss. Deshalb beschreiben wir ihn im Rest dieses Abschnitts.

Kategorisierung nach Branching

Zunächst unterteilen wir die Unstable-API-Erweiterungen in verschiedene Unterkategorien. Wie DuckDB selbst folgen diese Erweiterungen demselben Branching-Schema wie DuckDB, bei dem eine Kombination aus main und vx.y-codename die Hauptrolle spielt. Wir definieren nun die drei Typen instabiler Erweiterungen anhand ihrer Anzahl aktiver Branches.

  • Single-branch-Erweiterungen haben nur den aktiven Branch main
  • Two-branch-Erweiterungen haben zwei aktive Branches: main und vx.y-codename
  • Three-branch-Erweiterungen haben drei aktive Branches: main, vx.y-codename und vx.<y+1>-codename

DuckDB-Ziele

Jede Unstable-API-Erweiterung sollte eine einzige DuckDB-Version als Ziel haben. Diese Zielversion ergibt sich aus einer Kombination des duckdb-Submoduls und der Zielversion im Workflow MainDistributionPipeline. Welche Version eine Erweiterung als Ziel hat, hängt von der Phase des Release-Zyklus und vom Branch ab. Wir gehen nun alle Kombinationen durch

  • Phase: Mid-cycle
    • Typ: Single branch
      • Erweiterung main -> DuckDB vx.y.z oder main
    • Typ: Two branch
      • Erweiterung main -> DuckDB vx.y.z oder main
      • Erweiterung vx.y-codename -> DuckDB vx.y.z oder vx.y-codename
    • Typ: Three branch: sollte nicht existieren
  • Phase: Pre-release / Patch
    • Typ: Single branch
      • Erweiterung main -> DuckDB vx.y.z oder vx.<y+1>-codename
    • Typ: Two branch
      • Erweiterung main -> DuckDB vx.y.z oder vx.<y+1>-codename
      • Erweiterung vx.y-codename -> DuckDB vx.y.z oder vx.y-codename
    • Typ: Three branch
      • Erweiterung main -> DuckDB main
      • Erweiterung vx.y-codename -> DuckDB vx.y.z oder vx.y-codename
      • Erweiterung vx.<y+1>-codename -> DuckDB vx.<y+1>-codename

Wohin PRs gemergt werden

Wohin ein PR in eine Unstable-API-Erweiterung gemergt wird, hängt von zwei Dingen ab: der aktuellen Release-Phase und dem Erweiterungstyp. Wir gehen nun alle Kombinationen durch.

  • Phase: Mid-cycle
    • Typ: Single branch
      • wenn DuckDB-Ziel: vx.y.z:
        • PR für vx.y.<z+1> in main1
        • PR für vx.<y+1>.0 wird in main gemergt
      • wenn DuckDB-Ziel: main:
        • PRs für vx.y.<z+1> sind unmöglich
        • PR für vx.<y+1>.0 wird in main gemergt
    • Typ: Two branch
      • PR für vx.y.<z+1> wird in vx.y-codename gemergt
      • PR für vx.<y+1>.0 wird in main gemergt
    • Typ: Three branch
      • PR für vx.y.<z+1> wird in vx.y-codename gemergt
      • PR für vx.<y+1>.0 wird in vx.<y+1>-codename gemergt
      • PR für vx.<y+2>.0 wird in main gemergt
  • Phase: Pre-release / Patch
    • Typ: Single branch
      • wenn DuckDB-Ziel: vx.y.z:
        • PR für vx.y.<z+1> in main1 2
        • PR für vx.<y+1>.0 wird in main gemergt
      • wenn DuckDB-Ziel: main:
        • PRs für vx.y.<z+1> sind unmöglich
        • PR für vx.<y+1>.0 wird in main gemergt
    • Typ: Two branch
      • PR für vx.y.<z+1> wird in vx.y-codename gemergt 2
      • PR für vx.<y+1>.0 wird in main gemergt
    • Typ: Three branch
      • PR für vx.y.<z+1> wird in vx.y-codename gemergt2
      • PR für vx.<y+1>.0 wird in vx.<y+1>-codename gemergt
      • PR für vx.<y+2>.0 wird in main gemergt

Welche Erweiterungsversion wird veröffentlicht?

Zu jedem DuckDB-Release sollte ein vollständiger Satz aller Core-Erweiterungen verfügbar sein. Für Unstable-API-Erweiterungen bedeutet das einen Rebuild der Binärdateien. Für die Core-Erweiterungen erfolgt dieser Build in der Regel über die CI von duckdb/duckdb. Das bedeutet, dass die Liste der Erweiterungen, die zum Release verfügbar sein werden, in den Extension-Config-Dateien dokumentiert ist. Diese Config- Datei ist jedoch nicht immer aktuell. Um zu entscheiden, welche Version einer Erweiterung Teil des kommenden Releases sein soll, definieren wir die folgenden Quellen der Wahrheit für die neueste Erweiterungsversion anhand des Release-Typs (Major/Minor) und des Erweiterungs- typs (Single-/Multi-Branch):

  • Release-Typ: Patch
    • Erweiterungstyp: Single branch
    • Erweiterungstyp: Multi branch
      • Neueste Version: Branch vx.y-codename der Erweiterung
  • Release-Typ: Minor
    • Erweiterungstyp: Single branch
      • Neueste Version: Branch main der Erweiterung
    • Erweiterungstyp: Two branch
      • Neueste Version: Branch main der Erweiterung
    • Erweiterungstyp: Three branch
      • Neueste Version: Branch vx.<y+1>-codename der Erweiterung

Wechsel zwischen Single Branch, Two Branch und Three Branch

Der Wechsel zwischen den verschiedenen Branch-Typen für Erweiterungen ist vergleichsweise einfach und sollte wie folgt erfolgen:

  • Wechsel: Single branch -> Two branch
    • Wann: in jeder Phase
    • Gründe:
      • Wenn Features gemergt werden sollen, die nicht für vx.y.<z+1> geeignet sind, die Fähigkeit zu Releases für vx.y.<z+n> aber erhalten bleiben soll
      • Um mit dem aktuellen DuckDB-main testen zu können und gleichzeitig Releases für vx.y.<z+n> (einschließlich vx.y.z selbst) zu ermöglichen
    • Aktionen:
      • Branch vx.y-codename von einem Commit auf main zwischen HEAD von main und dem Commit in der DuckDB-vx.y.z-Config-Datei anlegen.
  • Wechsel: Two branch -> Three branch
    • Wann: in der Phase Pre-release oder Feature-freeze
    • Gründe:
      • Immer wenn ein Feature gemergt werden muss, das nicht für vx.<y+1>.0 zulässig ist.
    • Aktionen:
      • Branch vx.<y+1>-codename von main anlegen
  • Wechsel Three branch -> Two branch oder Two branch -> Single branch
    • Wann: Teil des Übergangs von Feature Freeze -> Mid-cycle
    • Aktion: geschieht automatisch (vx.y-codename wird per Definition inaktiv)

Footnotes

  1. Single-branch-Erweiterungen erfordern manuelle Versionsaktualisierungen, damit Änderungen im angezielten Release enthalten sind. ↩ ↩2

  2. Patch-Releases während der Pre-release- oder Feature-Freeze-Phase sind unüblich. Erwägen Sie, Änderungen stattdessen für das nächste Minor-Release vorzusehen. ↩ ↩2 ↩3

Dies ist eine inoffizielle Website und nicht mit DuckDB verbunden. Offizielle Seite:duckdb.org.duckdb.ubitools.com · Übersetzt und erstellt mit Astro und daisyUI