Управление версиями

Пакеты должны соответствовать семантической версии (SemVer). Семантическое управление версиями — это стратегия, которая позволяет авторам пакетов предоставлять информацию о типах изменений, включенных в данную версию, по сравнению с предыдущей версией в формате, который могут использовать автоматизированные инструменты.

Семантическое управление версиями выражает версии как MAJOR.MINOR.PATCH, где MAJOR.MINOR.PATCH, где MAJOR вносит одно или несколько критических изменений, MINOR вносит одно или несколько обратно совместимых изменений API, а PATCH только вводит исправления ошибок без API. вообще меняется.

Приступая к разработке пакета, начните номер версии с 0.1.0. ОСНОВНОЙ номер версии 0 зарезервирован для пакетов, находящихся на начальной стадии разработки. Во время первоначальной разработки API-интерфейсы пакетов часто меняются, часто ломая их, поэтому оставьте ОСНОВНОЙ номер версии 0, пока вы не сочтете, что ваш пакет достаточно стабилен и готов к использованию в рабочей среде.

После того, как пакет будет официально готов к использованию в рабочей среде, увеличьте ОСНОВНУЮ версию до 1 и придерживайтесь следующих рекомендаций для последующих изменений:

Увеличение значений:	В условиях:	Пример:
MAJOR	Существует по крайней мере одно критическое изменение, и ни одна версия пакета не может быть заменена другой. К критическим изменениям относятся: • Изменение поверхности API (открытая часть API) или функций таким образом, что это может привести к ошибкам компиляции или выполнения. • Удаление функций, не относящихся к API, включая удаление Активов или изменение GUID Актива. • Удаление или переименование сборок и ресурсов (поскольку) компилятор может не найти их). Примечание. При увеличении основной версии всегда сбрасывайте значения PATCH и MINOR на 0.	Версии 1.2.3 и 2.0.0 несовместимы и не могут использоваться взаимозаменяемо без риска.
MINOR (same MAJOR value)	Самое высокое значение MINOR обеспечивает обратную совместимость функциональности. К обратно совместимым (или некритичным) изменениям API относятся: • Изменение поверхности или функций API без риска ошибок компиляции или выполнения. • Добавление функций, не относящихся к API. • Добавление сборок и ресурсов (поскольку новые элементы не имеют ранее существовавших ссылок). Примечание. При увеличении дополнительной версии всегда сбрасывайте версию PATCH на 0.	Вы можете использовать версию 1.3.0 для реализации зависимости от версии 1.2.0, поскольку версия 1.3.0 обратно совместима. Вы не можете использовать 1.2.0 для реализации зависимости от 1.3.0.
PATCH (same MAJOR.MINOR values)	Наиболее высокий PATCH вводит исправления ошибок без изменения API вообще, с обратной совместимостью. API не меняется, если: • Поверхность API идентична, а функции остались без изменений. • Изменения не затрагивают общедоступный API.	Версии 1.3.0 и 1.3.1 должны быть взаимозаменяемы, так как они имеют один и тот же API, даже несмотря на то, что 1.3.1 содержит исправление ошибки, отсутствующее в 1.3.0.

Следование этим методам управления версиями позволяет диспетчеру пакетов автоматически разрешать конфликты (когда это возможно) или обновлять пакеты до более новых, обратно совместимых версий.

В следующих разделах описаны сценарии, которые помогут вам определить, как эти правила влияют на различные элементы пакета:

• Общие ресурсы (например, аудио, текстуры и модели).
• Определения сборки (файлы .asmdef) и предварительно скомпилированные сборки (управляемые файлы .dll)
• Файлы манифеста пакета (package.json)
• Устаревшие API

В дополнение к этим сценариям существует еще один фактор, который может повлиять на некоторые изменения, которые обычно требуют только MINOR или PATCH версии: включено ли свойство Auto Referenced. или отключен.

Автоматические ссылки

Одним из свойств, которые вы можете установить для своих определений сборки, является свойство Auto Referenced, которое определяет, будет ли Unity автоматически ссылаться на файл во время компиляции. Когда это свойство включено, некоторые изменения, для которых обычно требуется только увеличение версии MINOR или PATCH, теперь становятся критическими изменениями.

Когда вы выключаете(disable) автоссылку, если вы вносите какие-либо изменения, которые приводят к доступности новой сборки, вы вносите обратно совместимое изменение в API. Изменения API с обратной совместимостью, такие как добавление платформ, отключение ссылок на тесты Unity, добавление нового .asmdef или удаление ограничений определения, требуется только MINOR увеличение.

Однако, когда вы включаете(enable) автоссылку, эта вновь добавленная сборка неявно добавляется к ссылкам на различные другие сборки. Поскольку эти случаи могут привести к ошибкам компиляции в других сборках, требуется MAJOR увеличение.

Другой распространенный случай возникает, когда вы добавляете или изменяете версии пакета зависимость
См. в Словарь. В большинстве случаев изменение зависимости пакета требует только увеличения PATCH. Однако новая версия пакета может содержать сборку со свойством Auto Referenced, enabled, что становится критическим изменением и, следовательно, требует MAJOR увеличения. .

Чтобы избежать подобных проблем, всегда старайтесь не помещать сторонний файл DLL в несвязанный пакет (например, включать Newtonsoft.Json.dll в пакет SaveGameManager).

Assets

Проект может ссылаться на любой актив, видимый в базе данных активов. База данных активов однозначно отслеживает эти активы, используя идентификаторы GUID, определенные в их файлах .meta.

Когда вы вносите одно из этих изменений в общедоступный API, для этого требуется новая MAJOR версия, поскольку они нарушают изменения:

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

Сборки

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

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

Большинство свойств влияют на потребителей сборки, поэтому изменение любого из этих свойств представляет собой изменение общедоступного API пакета. Другие свойства не влияют на потребителей сборки, поэтому изменение любого из них не считается изменением API пакета.

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

Unity может либо предварительно скомпилировать сборки, либо скомпилировать их из скриптов и определения сборки. Таким образом, все, что относится к определениям сборок, обычно применимо и к предварительно скомпилированным сборкам.

В этом разделе подробно описаны изменения в определениях сборок и предварительно скомпилированных сборок, а также их влияние на версию пакета:

• Ключевые изменения (разрешены только в новых MAJOR выпусках)
• Изменения API, совместимые с предыдущими версиями (разрешены в новых MAJOR или MINOR выпусках)
• Обратно совместимые изменения, не влияющие на API (разрешены в новых MAJOR, MINOR или PATCH выпусках)

Только MAJOR: критические изменения

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

Обратите внимание, что следующее относится как к сборкам времени выполнения, так и к сборкам редактора, которые потребляются и используются пакетами. Это не относится к тестовым сборкам, поскольку пакеты обычно их не используют, поэтому они не являются частью API пакета.

Сценарий:	Почему компилятор не может найти указанную сборку:
Удаление определения сборки или предварительно скомпилированной сборки	Удаление файла определения сборки не позволяет конвейеру компиляции создать соответствующую сборку. Примечание. Начиная с версии 2019.1, отсутствующие ссылки разрешены для поддержки варианта использования «необязательная ссылка», но переименование сборки, необходимой Unity для компиляции определения сборки, вызывает ошибки компиляции. Аналогичным образом, если скомпилированному коду требуется тип из сборки, переименование этой сборки может привести к ошибкам времени выполнения, таким как TypeLoadException.
Изменение имени сборки (в файле .asmdef или переименование файла .dll)	Изменение имени сборки эквивалентно удалению сборки и добавлению новой с другим именем. Это означает, что Unity считает исходную сборку отсутствующей, хотя API по-прежнему содержит тот же код сборки под другим именем.
Добавление определения ограничения в .asmdef	Если вы добавите ограничение определения, Unity пропустит компиляцию сборки всякий раз, когда ограничение определения не выполняется. Это создает случаи, когда сборка отсутствует, хотя ранее она была доступна.
Удаление платформ	Если вы удалите поддержку определенной платформы, Unity больше не будет импортировать сборку на эту платформу, что равносильно удалению сборки. Вы можете удалить платформу, включив одно из следующих свойств: • includePlatforms, что нарушает совместимость со всеми незарегистрированными платформами • excludePlatforms, который добавляет к нему записи
Перенос общедоступных API из одной сборки в другую	При перемещении общедоступного кода из сборки A в сборку B любая сборка, которая ссылается на A, но не на B, не сможет скомпилироваться. Для определений сборки: если вы перемещаете скрипты, вы можете перемещать общедоступные API в другую сборку.
Изменение свойства Автоматически ссылаться	Когда вы отключаете свойство Auto Referenced, вы больше не можете использовать общедоступный API этой сборки без явной ссылки: • Для предварительно скомпилированных сборок отключение этого свойства предотвращает неявное добавление предварительно скомпилированной сборки Unity в качестве ссылки к определениям сборки и сборкам, скомпилированным в проекте. • Для определений сборок отключение этого свойства запрещает Unity неявно добавлять результирующую сборку в качестве ссылки на сборки, скомпилированные в проекте. Когда вы включаете свойство Auto Referenced, это может привести к конфликтам с другими изменениями в API, свойствах или зависимостях. Дополнительную информацию см. в разделе Автоматические ссылки.
Включение свойства Unity References → Test Assemblies в определениях сборок	Включение свойства Unity References → Test Assemblies помечает эту сборку как тестовую, и Unity обычно не включает ее в сборки (или не компилирует в некоторых случаях). Когда это происходит, любая сборка, ссылающаяся на отсутствующую сборку, не может найти ее, если только она не является тестовой сборкой.

MAJOR, MINOR: некритические изменения API

Следующие изменения являются обратно совместимыми или некритическими изменениями API. Все эти сценарии добавляют сборку, в отличие от критических изменений, которые удаляют сборку. Поскольку добавление сборки увеличивает поверхность API (открытую часть API), это считается изменением API. Однако существующих ссылок нет, поэтому добавление новой сборки не повлияет на другие сборки, созданные с помощью более раннего API.

Для изменений, совместимых с предыдущими версиями, требуется по крайней мере новый выпуск MINOR. Если вы включаете другие обновления, которые нарушают изменения, они также могут быть частью нового MAJOR выпуска.

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

Сценарий	Почему эти изменения не нарушают компиляцию
Удаление ограничения define в .asmdef	Снятие ограничения определения означает, что конвейеры компиляции и сценариев больше не пропускают эту сборку. Поскольку Unity всегда создает эту сборку, компилятор всегда может разрешать ссылки на нее, независимо от того, соблюдается ли это ограничение определения.
Добавление платформ	Добавление платформ не влияет на поддержку существующих платформ, поэтому оно обратно совместимо. Это изменение API, поскольку оно увеличивает поверхность API. Вы можете добавить платформы, изменив эти свойства: • Добавьте записи в свойство includePlatforms. • Полностью удалите свойство includePlatforms. Это эквивалентно добавлению всех платформ, которых еще нет в свойстве includePlatforms. • Удалить записи из свойства excludePlatforms.
Создание определения сборки с новыми сценариями (ранее не в другом файле .asmdef)	Добавление новой сборки увеличивает поверхность API (открытую часть API) без изменения каких-либо существующих реализаций.
Отключение свойства Unity References → Test Assemblies в файлах определения сборок	Отключение свойства Unity References → Test Assemblies помечает эту сборку как обычную сборку, поэтому Unity больше не обрабатывает ее иначе, чем любое определение сборки. Это изменение API, поскольку оно увеличивает поверхность API.

MAJOR, MINOR, PATCH: без изменений API

Следующие изменения не влияют на общедоступный API и разрешены в выпусках PATCH. Изменения в этих сценариях не влияют на общедоступный API, поскольку они не влияют на поверхность API (открытую часть API) и ничего не меняют для других потребителей.

Для изменений, не влияющих на общедоступный API, требуется как минимум новый выпуск PATCH. Если вы включаете другие обновления, которые вносят критические или некритические изменения, вы также можете включить их в MAJOR или MINOR выпуски.

Сценарий	Почему эти изменения не влияют на других потребителей
Изменение списка связанных сборок и определений сборок в файлах .asmdef	Сборка, которая ссылается на другую сборку, не ссылается автоматически на собственные ссылки этой другой сборки, но должна явно указывать их в списке. Поэтому изменение ссылок в определении сборки или сборке не влияет на других потребителей.
Изменение свойства Разрешить небезопасный код в определениях сборки	Это свойство определяет, разрешено ли компилятору компилировать код с модификатором unsafe. Изменение этого флага само по себе не меняет общедоступный API.
Изменение свойства Переопределить ссылки в определениях сборки	Это свойство управляет тем, как Unity вызывает компилятор для этой сборки, и не влияет на потребителей результирующей сборки. Изменение этого флага само по себе не меняет общедоступный API.

Файлы манифеста пакета

манифест пакетаКаждый пакет имеет манифест, который предоставляет информацию о пакете диспетчеру пакетов. Манифест содержит такую информацию, как имя пакета, его версия, описание для пользователей, зависимости от других пакетов (если есть) и другие подробности. Подробнее
См. в файле Словарь (package.json ) указывает имя, версию, зависимости пакета и другие метаданные о самом пакете.

В этом разделе подробно описаны изменения в файлах манифеста пакета и их влияние на версию пакета:

• Изменение имени (не разрешено)
• Изменения в зависимостях (контекст определяет минимальное изменение версии)
• Другие изменения (разрешены в новых MAJOR, MINOR или PATCH выпусках)

Изменение имени (не разрешено)

Изменение свойства name эквивалентно удалению одного пакета и добавлению нового пакета с другим именем и не поддерживается. Вы не можете переименовать пакет, пытаясь выпустить обновление: вы должны выпустить его как совершенно новый пакет. Изменение имени запрещено, поскольку существующие проекты и пакеты не могут интерпретировать имена как синонимы.

Dependency changes

Изменение зависимости в проекте само по себе не требует другой MAJOR или MINOR версии, если только это не является частью изменения API или если включено свойство Auto Referenced. .

В этом разделе приведены примеры изменений зависимостей и контексты, в которых они применяются (при условии, что свойство Автоматически ссылаться отключено и нет никаких изменений в API, кроме тех, которые в каждом случае описывает):

Изменение зависимости	Контекст	Минимальное изменение версии
Добавление новой зависимости	• Используется новый пакет без изменения функционального поведения и не меняется поверхность API.	PATCH
	• Использует новый пакет для введения нового поведения без изменения поверхности API. • Создает новые API, предоставляющие типы, определенные в новом пакете.	MINOR
	• Использует новый пакет для изменения существующего поведения без обратной совместимости без изменения поверхности API. • Изменяет существующие API таким образом, чтобы они не были совместимы с предыдущими версиями, чтобы предоставлять типы, определенные в новом пакете.	MAJOR
Удаление зависимости	• Удаляет пакет без изменения функционального поведения и не изменяет поверхность API.	PATCH
	• Удаление пакета приводит к изменению существующего поведения без обратной совместимости и без изменения поверхности API. • Удаляет API, предоставляющие типы, определенные в этой зависимости.	MAJOR
Изменение зависимости	• Использует измененный пакет без изменения функционального поведения и не изменяет поверхность API.	PATCH
	• Использует измененный пакет для введения нового поведения без изменения поверхности API. • Создает новые API, предоставляющие типы, определенные в измененном пакете.	MINOR
	• Использует модифицированный пакет для изменения существующего поведения таким образом, который не обеспечивает обратной совместимости, без изменения поверхности API. • Изменяет существующие API таким образом, чтобы они не были совместимы с предыдущими версиями, чтобы предоставлять типы, определенные в измененном пакете. • Предоставляет доступ к некоторым типам в API, которые изменены несовместимым с предыдущими способами в измененном пакете. • Предоставляет доступ к некоторым типам в API, которые больше не определены в измененном пакете.	MAJOR

MAJOR, MINOR или PATCH: другие изменения

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

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

Примечание. Изменения в свойствах unity или unityRelease в манифесте пакета всегда требуют выпуска MINOR или MAJOR. Несмотря на то, что свойства не влияют на сам API пакета, увеличение версии Unity определенно исключает работу версии пакета в предыдущих редакторах Unity и может привести к поломке зависимого проекта или пакета, в то время как уменьшение версии Unity делает пакет доступным для старых редакторов Unity.

Устаревшие и устаревшие API

Если вы хотите удалить некоторые функции из своего API, сначала выпустите хотя бы одну MINOR версию, содержащую устаревшую версию. Это предупреждает пользователей о предстоящем удалении, чтобы они могли плавно перейти на новый API. Затем вы можете удалить эту функциональность в новом MAJOR выпуске.

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

В этом случае вы можете выбрать способ устранения предупреждения-как-ошибки (в порядке убывания типичной желательности):

• Измените свой код, чтобы больше не использовать API.
• Оберните код, использующий API, в директивы #pragma warning, чтобы отключить предупреждение.
• Отключить предупреждения CS0612 (Устарело) и CS0618 (Устарело с сообщением).
• Отключите предупреждения как ошибки в вашем проекте.