Versionierung in QUIQQER

Dieses Dokument beschreibt wie in QUIQQER Versionen festgelegt werden. Es soll für Plugin und Modul Maintainer ein kleiner Leitfaden sein und soll Ungereimtheiten beseitigen.

Es gelten die folgenden Grundlagen:

• QUIQQER hält sich an die SemVer Notation. Es wird vorausgesetzt, dass die Grundlagen bekannt sind.
• Für die Entwicklung und Versionierung wird git als Versionsverwaltung genutzt
• Alle QUIQQER Module sind unter https://dev.quiqqer.com/ zu finden
• Die QUIQQER Module werden zusätzlich nach https://github.com/quiqqer gespiegelt

Für Redakteure und Nicht-Entwickler

Ein QUIQQER Paket (Modul / Plugin) besteht immer aus verschiedenen Entwicklungszweigen (Branches). Ein Branch repräsentiert also einen bestimmten Entwicklungsstand des Paketes. So zum Beispiel eine bestimmte Version.

Ein Paket kann (unter anderem) die nachfolgenden Branches aufweisen:

master (dev-master)

Der master Zweig beinhaltet folgendes:

• Im master Zweig sind Behebungen oder Features vorhanden welche schon fertig entwickelt sind.
• Im master Zweig kann es jedoch vorkommen das nicht alle Features getestet sind.

Da unter Umständen nicht alle Features getestet sind, ist der master Zweig nur eingeschränkt für den Produktivbetrieb zu empfehlen.

dev (dev-dev)

Der dev Zweig beinhaltet immer die aktuellste - möglicherweise instabile - Version eines QUIQQER Paketes.

• In diesem Zweig wird direkt entwickelt
• Diese Version des Paketes weist oft eine starke Instabilität auf

Diese Version ist nur für Entwickler vorgesehen und niemals für den Produktivbetrieb geeignet.

Versionen (1.0, 2.0)

Jede Haupt-/Major-Version besitzt einen eigenen Branch. Je nach Größe des Projektes erhalten auch Minor-/Neben-Versionen ihren eigenen Branch.

Diese Versionen sind getestet und wurden für stabil befunden. Damit sind sie für den Live Betrieb geeignet.

Für Entwickler

Grundlegende Entwicklungs-Branches (dev und master)

Wenn du als Entwickler ein neues Paket anlegst, sollten die Branches dev und master direkt zu Anfang angelegt werden. Diese zwei Branches sind die Grundlage für dein neues Repository.

Der Branch dev wird für die aktive Entwicklung genutzt und darf instabilen Code enthalten.
Der Branch master beinhaltet fertiggestellte Funktionen und Fehlerbehebungen, die stabil sein sollten aber noch ungetestet sein können. Die einzigen Commits auf diesem Branch sollten per Merge aus dem dev-Branch erstellt werden, sobald dort etwas fertiggestellt wurde.

Wichtig: in den Branches dev und master darf in der composer.json keine version-Eigenschaft existieren!

Versions-Branches

Ein Versions-Branches beinhaltet alle Minor-Versionen eines Pakets. Der Versions-Branch 1.2 beinhaltet also bspw. die Minor-Versionen 1.2.0, 1.2.1, 1.2.2 usw. aber jedoch nicht die Version 1.3.0 oder 1.1.9.

Wenn dein master-Branch in einem stabilen Zustand und vollständig getestet ist, kannst du daraus einen Versions-Branch abzweigen.

Versions-Branches sollten wie folgt benannt werden: <major version number>.<minor version number>.
Also zum Beispiel: 1.0, 1.1, 1.2 oder 2.0.

Um einen Versions-Branch per git zu erstellen kannst du folgendes Befehle in der Konsole ausführen:

# Sicherstellen, dass du auf dem master Branch bist
git checkout master

# Sicherstellen, dass du die aktuellste Version des Branches lokal vorliegen hast
git pull --rebase

# Erstelle deinen Versions-Branch
git checkout -b 1.0

# Pushe deinen Versions-Branch
git push origin 1.0

Eine neue Major- oder Minor-Version veröffentlichen (Release)

QUIQQER nutzt GitLab als Projektverwaltung. Releases sind in GitLab sehr einfach umzusetzen, daher solltest du auch GitLab als Oberfläche nutzen.

Wir gehen davon aus, das die Branches dev und master existieren.
Du hast nun deine fertiggestellten Änderungen vom dev in den master-Branch gemerged und dort sichergestellt, dass alles korrekt funktioniert. Nun kannst du einen neue(n) Release/Version erstellen:

• Lege ausgehend von deinem master-Branch einen Versions-Branch - wie oben beschrieben - an
• Wechsle in den Versions-Branch und erweitere die composer.json um einen Versions-Eintrag mit deiner gewünschten Version nach dem Muster <major>.<minor>.<patch> (also z.B: "version": "1.0.0")
• Commite deine Änderungen an der composer.json mit der folgenden Nachricht: refactor: version <Versionsnummer>. Also z.B.: refactor: version 1.0.0
• Pushe deine Änderungen auf den Versions-Branch: git push

Jetzt musst du nur noch ein Tag für deine neue Version anlegen, um dadurch ein Release zu markieren. Hierzu gehst du wie folgt vor:

• Öffne dein Projekt in GitLab und rufe den Bereich Repository > Tags auf
• Klicke (oben rechts) auf den Button New tag
• Fülle alle Felder wie folgt aus:
  • Tag name: deine Versionsnummer - also z.B. 1.0.0
  • Create from: dein Versions-Branch - also z.B. 1.0
  • Message: refactor: version <deine Versionsnummer> - also z.B. refactor: version 1.0.0
  • Release notes: Hier listest du alle neuen Features und Fixes deiner Version (im Markdown-Format) auf. Dazu kannst du die nachfolgende Vorlage nutzen (Simplen Changelog generieren: git log --no-merges --oneline <letzes Versions-Tag>..HEAD):

## Release notes for `<deine Versionsnummer>`

### Features

- <Feature 1>
- <Feature 2>

### Fixes

- <Fix 1>

Beispiele dazu findest du z.B. in den quiqqer/quiqqer-Releases

Wenn du alles richtig gemacht hast, taucht das neue Release auf der Release Seite deines Moduls (Project Overview > Releases) auf.

Einen Patch veröffentlichen/erstellen (z.B. 1.0.x)

Damit du ein Patch veröffentlichen kannst, ist ein weniger kompliziertes Vorgehen nötig:

• Stelle sicher, dass sich die Änderungen deines Patches im master-Branch befinden
• Wechsel in den Versions-Branch zu dem du den Patch hinzufügen möchtest (z.B. git checkout 1.0)
• Merge den master-Branch in den Versions-Branch: git merge master
• Während du noch im Versions-Branch bist, aktualisiere die Version in der composer.json (z.B. "version": "1.0.1")
• Erstelle wie oben beschrieben einen neuen Tag und Release für den Patch (z.B. 1.0.1)