Versionierungssystem und Repository Branch Layout

With the release for beta we’ve moved SpongeAPI versioning to semantic versioning (see https://semver.org/). This change means that every time that we make a release we have to increment the version according to the rules of SemVer.

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

The core of our repositories is the bleeding branch. Almost all changes will be added to bleeding, including new features, changes, and bugfixes. The version of bleeding will always be the next major release version appended with -SNAPSHOT (e.g. 6.0.0-SNAPSHOT) to denote that it is not yet a final build and subject to change.

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

The SpongeDocs themselves are unversioned following our philosophy that they will never be finished, but instead in a constant flux of ever increasing usability. However, they target a specific version of the API, generally the most recent release of SpongeAPI.

Kernbranch

Der Hauptbranch für SpongeDocs ist stable. Jeder neue Commit in stable löst einen Neubau der Docs Website <https://docs.spongepowered.org/>`_aus. Commits in ``stable` 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.

A feature branch may only be merged into master if the changes / additions made in it are correct regarding the SpongeAPI release currently targeted by the SpongeDocs. Any feature branches that describe features not yet included in a release stay unmerged until the corresponding API version is released and becomes the new targeted version for the SpongeDocs. However, the Docs team might collect additions for a specific version on a single branch.

release branch example

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.