|
|
# 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](https://semver.org/). Es wird vorausgesetzt, dass die Grundlagen bekannt sind.
|
|
|
* Für die Entwicklung und Versionierung wird [git](https://git-scm.com/) 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:
|
|
|
|
|
|
```bash
|
|
|
# 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`):
|
|
|
```markdown
|
|
|
## Release notes for `<deine Versionsnummer>`
|
|
|
|
|
|
### Features
|
|
|
|
|
|
- <Feature 1>
|
|
|
- <Feature 2>
|
|
|
|
|
|
### Fixes
|
|
|
|
|
|
- <Fix 1>
|
|
|
```
|
|
|
Beispiele dazu findest du z.B. in den [`quiqqer/quiqqer`-Releases](https://dev.quiqqer.com/quiqqer/quiqqer/-/releases/1.4.0)
|
|
|
|
|
|
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`) |
|
|
\ No newline at end of file |