Versionierungssystem und Repository Branch Layout
Mit der Veröffentlichung der Beta haben wir das Versionierungskonzept der SpongeAPI auf ein semantische Versionierung geändert (Siehe http://semver.org/). Diese Änderung hat zur Folge, dass jedes Mal, wenn wir eine Version veröffentlichen, wir die Versionsnummer entsprechend der Regeln von SemVer hochzählen müssen.
SemVer
SemVer verwendet das Schema X.Y.Z, wobei X eine Haupt-Version, Y eine Unter-Version und zu schließlich Z eine Patch-Version ist. Eine Version, die Änderungen enthält, die nicht rückwärts-kompatibel sind, muss eine Haupt-Version weiter sein, als das vorherige Release. Wenn es nur ein paar neue Features gibt, die aber alle rückwärts-kompatibel sind, dann wird die Unter-Versionsnummer hochgezählt. Sollte die Version ausschließlich Fehlerkorrekturen enthalten, dann wird auch nur die Patch-Version hochgezählt.
Daraus folgt, dass zum Beispiel Version 3.2.0 vollständig kompatibel mit 3.0.0, während Version 4.0.0 nicht kompatibel mit 3.0.0 ist. Die Versionen 3.1.0 und 3.1.2 sind, bis auf die behobenen Fehler, vollständig untereinander austauschbar.
Die Struktur unserer Branches (unten näher beschrieben) ist darauf ausgelegt, diesen Prozess zu unterstützen, indem sie uns ermöglicht, kleine Releases zu erstellen, ohne, dass inkompatible Änderungen uns zwingen eine neue Hauptversion zu veröffentlichen. Diese Struktur verwenden wir für die SpongeAPI, SpongeCommon, SpongeForge, and SpongeVanilla Repositories, aber nicht für die SpongeDocs.
SpongeAPI, SpongeCommon, SpongeForge und SpongeVanilla
Der Bleeding Branch
Der Mittelpunkt unserer Repositories ist der bleeding Branch. Fast alle Änderungen werden dort hinzugefügt, einschließlich neuer Features, Änderungen und Fehlerkorrekturen. Die Version von bleeding stellt immer die nächste Hauptversion da, allerdings um den Zusatz -SNAPSHOT ergänzt (z. Bsp.:6.0.0-SNAPSHOT), damit diese eindeutig als noch nicht fertige Version zu erkennen ist und sich noch einige Sachen ändern könnten.
Der Hauptgrund, warum wie einen bleeding Branch haben, ist, damit wir ein Testgebiet für unsere Änderungen haben. Selbst erfahrenen Sponge Teammitlgiedern kann es passieren, dass eine Version nicht funktioniert oder sie einen Fehler übersehen haben. Daher wird der bleeding Branch von Mitgliedern in der Gemeinschaft getestet, die immer die neuste Version haben wollen. So können wir schnell und einfach die auftauchenden Fehler korrigieren.
Stable Branches
Stable Branches stellen eine deutlich stabilere Plattform dar, auf der Plugin und Server Implementierungen erstellt werden können. In diesen Versionen wird es keine Inkompatibilitäten geben, sondern nur kompatible Änderungen. Für jede Hauptversion der API gibt es einen eigenen Branch, der die aktuellste API/Implementierung für diese Version enthält, inklusive der Nebenversionen und Fehlerkorrekturen.
Wenn es Zeit wird, eine neue Hauptversion zu veröffentlichen, wird ein neuer stable-x Branch von bleeding augehend erstellt, wobei x die neue Hauptversionsnummer ist. Zum Beispiel: stable-5. Im Anschluss wird in bleeding die Versionsnummer entsprechend auf die nächste Hauptversion hochgezählt, wie es oben beschrieben ist.
Änderungen, die schon seit längerem in bleeding sind, bei denen keine Fehler bekannt sind und die auf vorherige Hauptversionen anwendbar sind, werden mit Hilfe von cherry-pick für zukünftige Releases in den entsprechenden stable Branch übernommen. Die Änderungen werden gruppiert und als Unterversion veröffentlicht, sofern keine sofortige Fehlerkorrektur bevorzugt wird. In dem Fall wird eine Bugfix-Version erstellt. Jedes Mal, wenn eine Version veröffentlicht wird, wird im API Repository ein Tag erstellt, dass auf den für das Release verwendete Commit zeigt.
Feature Branches
Neue Features oder Änderungen sollten in einem feature/foo- oder fix/bar-Branch erstellt werden. Dieser sollte auf dem neusten Commit des bleeding-Branches aufbauen. Die einzige Ausnahme ist, wenn die Änderungen inkompatibel mit dem neusten bleeding-Commit sind. In diesem Fall sollten alle Änderungen auf stable-x aufbauen. Du solltest aber in deinem pull-Request, warum du nicht den Branch bleeding nehmen konntest - wie zum Beispiel einem Bugfix zu einem Feature, das von Mojang in einer späteren Version von Minecraft entfernt wurde.
Wenn die Änderungen bei keinem vorherigen Release für Probleme sorgen, kann es sein, dass das Sponge-Team die Änderungen in den einen oder anderen stable-Branch einfügt - vorausgesetzt keine Probleme entstehen, nachdem die Änderungen mit bleeding zusammengeführt wurden.
SpongeDocs
Die SpongeDocs selber sind nicht versioniert, sie folgen unserer Philosophie, dass sie nie fertig sein werden, sondern einen steten Wandel zu immer größerer Benutzbarkeit durchlaufen. Trotzdem beziehen sie sich auf eine besimmte Version der API, im Allgemeinen auf die neuste Veröffentlichung der SpongeAPI.
Kernbranch
Der Hauptbranch für SpongeDocs ist master. Jeder neue Commit in master löst einen Neubau der Docs Website <https://docs.spongepowered.org/>`_aus. Commits in ``master` werden für gewöhnlich gemacht, um Änderungen an der aktuellsten Version der SpongeAPI zu dokumentieren oder kleinere Fehler in der Dokumentation zu beheben.
Feature Branches
Wenn ein neues Feature beschrieben wird, werden ältere Texte aktualisiert, neu gefasst oder die Dokumente neu strukturiert. Dies geschieht in einem feature/foo- oder einem fix/bar-Branch. Diese Branches werden dann einer Überprüfung unterzogen und, sobald diese abgeschlossen ist, gemerged.
Ein Feature Branch wird nur in master gemerged, wenn die Änderungen / Hinzufügungen korrekt im Bezug auf die SpongeAPI Version, die aktuell von den SpongeDocs behandelt wird sind. Jeder Feature Branch, der Features beschreibt, die noch nicht in eine Version eingefügt sind, bleibt nicht gemerged, bis die entsprechende API-Version veröffentlich ist und von den SpongeDocs behandelt wird. Trotzdem kann das Docs-Team Ergänzungen für eine bestimmte Version auf einem Branch sammeln.
Release Branches
Die SpongeDocs verwenden release/x.y.z Branches, um Docs für ältere API Versionen zu veröffentlichen, wie API 3.1.0. Ältere APIs sind auf ihren entsprechenden Branches vorhanden. Wenn eine neue API veröffentlich wird, wird das Docs-Team einen neuen release/x.y.z Branch erstellen und master danach auf die neue API-Version bringen. Ein Commit zu einem release Branch löst auch eine Aktualisierung der älteren SpongeDocs Version aus, genauso, wie bei dem Core Branch.
