Система управления версиями и расположение ветвей репозитория

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 использует схему `` X.Y.Z``, где X это major версия, Y это minor, а Z — версия patch. Версия, содержащая изменения, которые не являются обратно совместимыми, должна быть на одну версию major выше предыдущей версии. Если есть только новые функции, которые по-прежнему совместимы с предыдущими версиями, то новая версия будет на одну minor версию выше предыдущей версии, и если выпуск содержит только исправления, то будет увеличена только версия patch.

Это означает, что, например, 3.2.0 полностью совместим с 3.0.0, в то время как 4.0.0 не является бинарно совместимой с 3.0.0. 3.1.0 и 3.1.2 полностью взаимозаменяемы, не считая исправленных ошибок.

The layout of our branches (described below) is designed to assist this process by allowing us to make minor releases without a breaking change forcing us to make it a major release. This branch layout applies to SpongeAPI, SpongeCommon, SpongeForge, and SpongeVanilla repositories but not to the SpongeDocs.

SpongeAPI, SpongeCommon, SpongeForge и SpongeVanilla

Ветвь Bleeding

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.

Основной причиной наличия ветви bleeding является наличие полигона для внесения изменений. Даже опытные члены команды Sponge могут случайно вызвать сбои в работе или пропустить ошибку. Секция bleeding будет протестирована людьми из сообщества, которые хотят получить самую последнюю версию, а это значит, что мы можем гораздо быстрее исправить возникающие ошибки.

Стабильные ветви

Стабильные ветви представляют собой гораздо более стабильную платформу, на которой могут быть реализованы плагины и серверные реализации. Не будет прерываний API, только неразрушающие дополнения. Существует ветвь, названная в честь каждой крупной версии API, которая содержит новейшие API/реализацию для этой версии, включая любые незначительные выпуски или выпуски исправлений.

Когда придет время выпуска основной версии, новая ветка stable-x будет создана из bleeding, где x это новая основная версия — например, stable-5. bleeding будет соответствующим образом обновлен до следующего крупного релиза, как описано выше.

Изменения, которые были в bleeding на некоторое время, которые не содержат известных ошибок, и которые могут быть применены к предыдущему главному выпуску, будут отправлены в соответствующую ветку stable для будущей версии. Изменения будут сгруппированы в новую второстепенную версию, если только не требуется немедленное исправление, в этом случае вместо этого будет создана версия с исправлением ошибок. Когда будет выпущена версия, в репозитории API будет создан тег, указывающий на коммит релиза.

Ветви функциональностей (Feature Branches)

Новые возможности или изменения должны быть созданы в ветке feature/foo или fix/bar. Это должно быть основано на самой последнем коммите bleeding. Единственное исключение в том случае, если изменения несовместимы с нарушающими изменениями bleeding, в этом случае вы должны основываться на соответствующем stable-x. В своем pull-request запросе вам необходимо указать, почему ваше изменение не может быть включено в bleeding — например, исправление ошибки в функции, которая была удалена Mojang в более поздней версии.

Если внесенные изменения не нарушают предыдущий релиз, команда Sponge также может включить некоторые изменения (cherry-pick) в одну или несколько stable ветвей, предполагая, что после слияния изменений в bleeding проблем не возникнет.

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.

Основная ветвь

Основной веткой для SpongeDocs является stable. Каждый новый коммит в stable вызывает пересборку сайта документации <https://docs.spongepowered.org/>`_. Коммиты в stable чаще всего делаются чтобы описать самый актуальный выпуск SpongeAPI или исправить частые ошибки в документации.

Ветви функциональностей (Feature Branches)

Всякий раз, когда описывается новая функция, старые тексты обновляются или изменяются или документы реструктурируются, это делается в ветке feature/foo или fix/bar. Затем эти ветви будут пересмотрены и, если они будут признаны завершенными, могут быть объединены.

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

Ветвь релиза

SpongeDocs использует ветви release/x.y.z для публикации документации для более старых версий API, таких как API 3.1.0. Более старые выпуски API доступны в соответствующих ветвях. Всякий раз, когда выпускается новая версия API, команда документации создают новую ветвь release/x.y.z и затем перемещает master на новую версию API. коммит в ветвь release также вызывает перестройку более старой версии документации, как и в основной ветке.