Unity 6.3
0 онлайн 25 гостей 3 в системе
Вход
← Руководство

Версирование пакетов

Версии пакетов в Unity соответствуют Конвенции Семантики Версий. Используя Семантику Версий, вы можете сообщать пользователям об объеме изменений при изменении ассетов, сборок, APIs или других элементов, влияющих на совместимость пакетов.

Примечание: На этой странице используется следующая терминология:

  • Потребитель относится к любому коду или проекту, который зависит от (и использует) ваш пакет, включая:
    • Unity проекты, которые устанавливают ваш пакет.
    • Другие пакеты, объявляющие ваш пакет в качестве зависимости.
    • Определения сборок (файлы.asmdef) в проекте, которые ссылаются на сборки вашего пакета.
    • Скрипты, ссылающиеся на ваши открытые типы или ассеты по глобально уникальным идентификаторам (GUID).
  • API поверхность — это всё, на что полагаются потребители: сборки и их открытые API, любые ассеты, на которые ссылаются по GUID, и ограничения манифеста пакета.

Конвенция Семантического Версирования использует формат major.minor.patch:

  • major: Увеличение этого элемента представляет собой разрушающее изменение. Изменения, которые удаляют или скрывают что-то, обычно считаются разрушающими изменениями.
  • minor: Увеличение этого элемента представляет собой обратно совместимые добавления или изменения.
  • patch: Увеличение этого элемента представляет исправления ошибок.

Основные рекомендации по семантическому версионированию

Запускайте новые пакеты с версией 0.1.0, пока APIs нестабильны. Номер главной версии 0 указывает, что пакеты находятся в начальной фазе разработки. В течение этой фазы пакет APIs часто меняется, зачастую в разрушающем стиле. Держите номер главной версии на уровне 0 до тех пор, пока вы не сочтете, что ваш пакет достаточно стабилен и готов для использования в производственной среде.

Когда пакет готов для производства, выпустить версию 1.0.0, затем:

  • Увеличивать главную версию при внесении изменений API, нарушающих обратную совместимость. Это означает, что код, работавший с предыдущей версией, может не работать с новой версией без модификаций.
    • Пример: Версии 1.2.3 и 2.0.0 несовместимы и не могут использоваться взаимозаменяемо без риска.
    • Примечание: При увеличении главной версии всегда сбросайте значения второстепенных версий и патчей на 0.
  • Увеличивать второстепенное значение каждый раз, когда вводится изменение функциональных возможностей обратно совместимым образом.
    • Пример: Вы можете использовать версию 1.3.0 для выполнения зависимости от 1.2.0, так как 1.3.0 является обратно совместимым. Однако вы не можете использовать 1.2.0 для выполнения зависимости от 1.3.0.
    • Примечание: При увеличении второстепенной версии всегда сбросайте версию патча на 0.
  • Увеличивать значение патча каждый раз, когда вы вводите исправление ошибки или любое небольшое обратно-совместимое изменение, которое не изменяет API.
    • Пример: Версии 1.3.0 и 1.3.1 взаимозаменяемы, так как они имеют одинаковую API, даже если 1.3.1 содержит исправление ошибки, не присутствующее в 1.3.0.

Package Manager Unity использует эти правила управления версиями для разрешения зависимостей и автоматического выбора совместимых версий пакетов.

Изменение номера версии

После определения номера версии для увеличения можно использовать один из следующих методов для установки номера версии:

  • Обновите поле Версия в окне Inspector.
  • Обновить свойство version в файле манифеста пакета.

Дополнительные сведения см. в разделе Изменение манифеста пакета.

Сводка правил версионирования

Следующая таблица резюмирует правила Семантики Версирования для увеличения частей номера версии. В последующих разделах подробно описываются эти изменения.

Площадь Изменить тип или контекст Минимальная версия для увеличения
Ассеты • Удалить ассет, видимый для базы данных ассетов.
• Изменить ассета GUID.		 Майор
Ассеты • Добавить ассеты или содержание, которые вводят новые функции. Незначительные
Ассеты • Настройка существующих ассетов или контента без изменения их GUID. Патч
Ассамблеи • Удаление или переименование сборки.
• Перенос публичных API между сборками.		 Майор
Ассамблеи • Удалить поддержку платформы.
• Добавить ограничение определения.
• Переключить параметр Автоматическая ссылка (см. Автоматическая ссылка.)		 Майор
Ассамблеи • Добавить сборку.
• Добавить платформы.
• Удалить ограничение определения.		 Незначительные
Ассамблеи • Изменение ссылок на сборку. Патч
Ассамблеи • Переключить Разрешить «небезопасный» код или Переопределить ссылки. См. изменения патча в сборках
Манифест пакета • Переименовать пакет (свойствоname). Не поддерживается
Манифест пакета • Добавление, удаление или изменение зависимости (только внутреннее, без изменения открытого API и поведения). Патч
Манифест пакета • Зависимость вводит новое поведение или подвергает новые типы через ваш API. Незначительные
Манифест пакета • Изменение зависимости изменяет поведение или API таким образом, что не является обратно совместимым. Майор
Манифест пакета • Увеличьте значение в свойстве unity или unityRelease. Незначительные или крупные
Скриптирование • Переименование или удаление открытых типов, методов, свойств, полей или событий.
• Изменение сигнатур (типов, количества или порядка параметров), возвращаемых типов либо видимости членов (с открытой на внутреннюю или закрытую).
• Переименование пространств имён либо перенос открытых типов или пространств имён между сборками.
• Изменение значений перечисления (enum) или их базовых типов.
• Удаление членов перечисления (enum).
• Изменение типов открытых полей или свойств, используемых в сериализации Unity (включая поля, отображаемые в Inspector окно.)
• Удаление или переименование серийных членов.		 Майор
Скриптирование • Добавление новых открытых типов, членов или событий.
• Добавить перегрузки или дополнительные параметры к существующим методам.		 Незначительные
Скриптирование • Внутренние или приватные рефакторинги.
• Повышение производительности.
• Исправления ошибок, не меняющие поверхность открытого API.
• Документация, комментарии или форматирование.		 Патч
Политика • Отметить APIs как устаревший. Незначительные
Политика • Удалить устаревший APIs. Майор

Для получения более подробной информации об этих правилах, см. соответствующие разделы деталей для активов, ассамблеи, манифест пакета, и политики.

Подробная информация об изменениях версий, касающихся ассетов

База данных ассетов отслеживает ассеты путем ссылки на GUID в файлах ассетов .meta.

Следующие существенные изменения требуют увеличения основного выпуска:

  • Удаление ассета, на который могут ссылаться проекты или пакеты.
  • Изменение GUID. ассета Если вы изменяете GUID ассета, База данных ассетов воспринимает это как удаление первоначального ассета, а затем добавление нового (идентичного) ассета. Это приводит к нарушению ссылки, поскольку первоначальная GUID больше не указывает на ассет, поэтому База данных ассетов не может разрешить ссылку.

Следующие неразрушающие изменения требуют увеличения второстепенной версии:

  • Добавление новых ассетов в качестве обратно совместимой функции.
  • Обновление содержимого ассета без изменения GUIDs, если добавление является функцией.

Следующие неразрушающие изменения требуют увеличения версии патча:

  • Обновление содержимого ассета без изменения GUIDs, если добавление является исправлением ошибки.

Сведения об изменениях версий, связанных со сборками

Определения сборок (.asmdef) определяют группу скриптов, которые конвейер компиляции Unity Editor использует для создания управляемых сборок (файлов.dll). Следующие инструкции также применимы к предкомпилированным сборкам.

Автоматическая ссылка в сборках

Свойство Auto Referenced в окне Assembly Definition Inspector определяет, будет ли Unity неявно ссылаться на сборку. Этим поведением также можно управлять с помощью свойства autoReferenced в файле определения сборки (.asmdef) пакета.

Увеличение главной или второстепенной версии в зависимости от сценария:

  • Добавление сборки, в которой включено свойство Auto Referenced, может вызвать конфликты компиляции в потребителях. В этом сценарии увеличите главную версию.
  • Добавление сборки, у которой отключено свойство Auto Referenced, является обратно совместимым. В этом сценарии увеличите второстепенную версию.

Избегайте объединения файлов сторонней библиотеки динамических ссылок (DLL) в несвязанные пакеты, что может привести к созданию неожиданных косвенных ссылок.

Разрушение изменений в сборках

Увеличение главной версии при внесении следующих изменений в сборку:

Обратно совместимые API изменения в сборках

Увеличение второстепенной версии при внесении неразрушающих изменений в сборку. Следующие изменения рассматриваются как неразрушающие изменения только при добавлении или изменении сборки в то время, как авто ссылка на свойство отключено:

Примечание: Если вы внесете эти изменения в сборку, авто ссылка на свойство В таких случаях вы должны увеличивать главную версию, а не второстепенную версию.

Нет API изменений в сборках

Увеличение версии исправления при внесении в сборку следующих неразрушающих изменений:

Эти изменения не затрагивают открытую поверхность API для потребителей.

Сведения об изменениях версий, связанных с манифестом пакета

Манифест пакета (package.json) определяет идентификатор пакета, его зависимости и метаданные.

Изменение названия

Изменение свойства name не поддерживается. Опубликуйте пакет как новый пакет с другим именем.

Изменения в подразделениях

В зависимости от изменения обновление зависимостей может потребовать увеличения различных частей номера версии.

Изменение Изменить тип или контекст Минимальная версия
Добавление зависимости • Изменения только во внутреннем API.
• Изменения без воздействия API и без изменений поведения.		 • Патч (Автоматический ссылки отключено)
• Главный (Автоматический ссылки включено)
Добавление зависимости • Изменения, которые вводят новое поведение.
• Изменения, которые выявляют новые типы в вашем API.		 • Незначительные (Автоматически ссылается отключено)
• Основные (Автоматически ссылается включено)
Добавление зависимости • Изменения, которые изменяют существующее поведение таким образом, что оно не является обратно совместимым.
• Изменения в существующем APIs.		 Майор
Удаление зависимости • Изменения только во внутреннем API без изменения поведения. Патч
Удаление зависимости • Изменения, нарушающие поведение
• Удаление APIs, которые раскрывают свои типы.		 Майор
Изменение версии зависимости • Изменения только во внутреннем API без изменения поведения. • Патч (Автоматический ссылки отключено)
• Главный (Автоматический ссылки включено)
Изменение версии зависимости • Изменения, которые вводят новое поведение.
• Изменения, которые выявляют новые типы в вашем API.		 • Незначительные (Автоматически ссылается отключено)
• Основные (Автоматически ссылается включено)
Изменение версии зависимости • Изменения, которые изменяют поведение или API, которые не являются обратно совместимыми. Майор

Другие явные изменения

Вы можете изменить свойства description, category, keywordsи displayName в любом выпуске. Рассмотрите возможность увеличения второстепенной версии, если изменения сопровождаются новыми возможностями.

Изменение свойств unity или unityRelease требует по крайней мере небольших приращений, так как эти изменения изменяют поддерживаемые версии Unity Editor. Увеличение версии Unity исключает возможность работы версии пакета с предыдущими редакторами Unity и может нарушить зависимый проект или пакет. Уменьшение версии Unity делает пакет доступным для более старых редакторов Unity.

Сведения об изменениях версий, связанных с политикой

Изменения политики включают устаревание и удаление пакетов.

При удалении функциональности из пакета:

  1. Увеличьте неосновную версию и выпустите пакет, пометив затронутые APIs как устаревшие. Включите сообщение и инструкцию.
  2. Увеличить главную версию и выпустить пакет, удалив те APIs.

Дополнительная информация