包版本控制

包必须遵循语义版本控制 （SemVer） 。语义版本控制是一种策略，它允许包作者以自动化工具可以使用的格式提供有关给定版本中包含的更改类型的信息，与以前版本相比。

语义版本控制将版本表示为 MAJOR。次要。PATCH，其中 MAJOR 引入了一个或多个重大更改，MINOR 引入了一个或多个向后兼容的 API 更改，而 PATCH 仅引入错误修复，根本没有 API 更改。

当您开始开发包时，请以0.1.0.主要版本号0为处于初始开发阶段的包保留。在初始开发期间，包 API 经常更改，并且经常以中断的方式更改，因此请将 MAJOR 版本号保持在0直到您认为您的包足够稳定并准备好在生产中使用。

在包正式准备好在生产中使用后，将 MAJOR 版本递增为1并遵守以下后续更改准则：

遵循这些版本控制做法允许包管理器自动解决冲突（如果可能），或将包升级到较新的向后兼容版本。

以下部分介绍了帮助您确定这些规则如何影响各种包元素的方案：

• 常规资产（如音频、纹理和模型）。
• 程序集定义 （.asmdef 文件） 和预编译程序集 （托管.dll文件）
• 包清单文件 （package.json)
• 过时的 API

除了这些方案之外，还有另一个因素可能会影响某些通常只需要增加 MINOR 或 PATCH 版本的更改：是启用还是禁用了“自动引用”属性。

自动引用

您可以为程序集定义设置的属性之一是 Auto Referenced 属性，该属性控制 Unity 是否在编译期间自动引用文件。启用此属性后，通常只需要增加 MINOR 或 PATCH 版本的某些更改现在将成为重大更改。

禁用自动引用时，如果进行任何更改导致新程序集可用，则会对 API 进行向后兼容的更改。向后兼容的 API 更改，例如添加平台、禁用 Unity 测试引用、添加新的 .asmdef 或删除定义约束，只需要稍微增加。

但是，启用自动引用时，新添加的程序集将隐式添加到各种其他程序集的引用中。由于这些情况可能会导致其他程序集中的编译错误，因此需要大幅增加。

另一种常见情况发生在添加或更改包依赖项的版本时。大多数时候，更改包依赖关系只需要增加 PATCH。但是，新包版本可能包含启用了“自动引用”属性的程序集，这将成为重大更改，因此需要大幅增加。

若要避免此类问题，请始终尽量避免将第三方 DLL 文件放入不相关的包中 （，例如在 SaveGameManager 包中包含 Newtonsoft.Json.dll） 。

资产

项目可以引用资产数据库可见的任何资产。资产数据库使用其 .meta 文件中定义的 GUID 唯一地跟踪这些资产。

当您向公共 API 引入其中一项更改时，这需要一个新的 MAJOR 版本，因为它们是重大更改：

组件

程序集定义 （.asmdef） 定义一组脚本一段代码，允许您创建自己的组件、触发游戏事件、随时间修改组件属性以及以您喜欢的任何方式响应用户输入。更多信息
请参阅术语表Unity 编辑器的编译管道将其转换为单独的托管程序集 （.dll）。这些 .asmdef 资产包括驱动生成程序集属性的属性。这包括：

• 导入器设置，例如包含和排除的平台
• 与编译相关的属性，例如输出程序集名称和提供给编译器以生成程序集的引用。

大多数属性都会对程序集的使用者产生影响，因此更改其中任何属性都构成对包的公共 API 的更改。其他属性对程序集的使用者没有影响，因此更改其中任何一个都不被视为更改包 API。

警告： “自动引用”属性是一种特殊情况，因为许多通常根本不会更改 API 或以向后兼容的方式更改 API 的更改可能会导致编译错误，具体取决于是否启用了它。有关详细信息，请参阅自动引用。

Unity 可以预编译程序集，也可以从脚本和程序集定义编译程序集。因此，适用于程序集定义的任何内容通常也适用于预编译程序集。

本部分详细介绍了程序集定义和预编译程序集的更改，以及对包版本的影响：

• 重大更改（仅在新的主要版本中允许）
• 向后兼容的 API 更改（在新的 MAJOR 或 MINOR 版本中允许）
• 不更改 API 的向后兼容更改（在新的 MAJOR、MINOR 或 PATCH 版本中允许）

仅限主要：重大更改

当您对公共 API 进行重大更改时，这需要新的 MAJOR 版本，因为它可能会导致编译和运行时错误。这些方案都会从引用程序集的任何其他程序集中删除或隐藏程序集。编译使用引用程序集中定义的类型的程序集时，如果编译器找不到其他程序集，则会导致编译错误。有关使用装配和装配定义的详细信息，请参阅装配定义。

请注意，以下内容适用于包使用和使用的运行时程序集和编辑器程序集。它不适用于测试程序集，因为包通常不使用它们，因此它们不是包 API 的一部分。

主要、次要：非中断性 API 更改

以下更改是向后兼容或非中断性的 API 更改。这些方案都添加了程序集，这与删除程序集的中断性更改不同。由于添加程序集会增加 API 图面（API 的公开部分），因此它被视为 API 更改。但是，没有现有引用，因此添加新程序集不会影响使用早期 API 创建的其他程序集。

向后兼容的更改至少需要一个新的 MINOR 版本。如果您包含其他重大更改的更新，则这些更新也可以是新 MAJOR 版本的一部分。

警告：仅当禁用“自动引用”属性时，这些更改才向后兼容。启用“自动引用”属性后，此表中列出的更改可能会导致中断性更改。有关详细信息，请参阅自动引用部分。

主要、次要、补丁：没有 API 更改

以下更改不会影响公共 API，并且在 PATCH 版本中是允许的。这些方案中的更改不会更改公共 API，因为它们不会影响 API 图面（API 的公开部分），也不会为其他使用者更改任何内容。

不更改公共 API 的更改至少需要新的 PATCH 版本。如果要包含引入中断性或非中断性更改的其他更新，则还可以将它们包含在主要或次要版本中。

包清单文件

这包清单每个包都有一个清单，该清单向包管理器提供有关包的信息。清单包含包的名称、版本、用户说明、对其他包的依赖关系（如果有）以及其他详细信息等信息。更多信息
请参阅术语表文件 （package.json） 指定名称、版本、包依赖项以及有关包本身的其他元数据。

本部分详细介绍了包清单文件中的更改以及对包版本的影响：

• 姓名更改（不允许）
• 依赖项的更改（上下文确定最小版本更改）
• 其他更改（在新的 MAJOR、MINOR 或 PATCH 版本中允许）

姓名更改（不允许）

更改 name 属性相当于删除一个包并添加一个具有不同名称的新包，并且不支持。您无法通过尝试发布更新来重命名包：您必须将其作为全新的包发布。不允许更改名称，因为现有项目和包无法将名称解释为同义词。

依赖项更改

更改项目中的依赖项本身不需要不同的 MAJOR 或 MINOR 版本，除非它是 API 更改的一部分，或者启用了 Auto Referenced 属性。

本节提供依赖项更改及其应用上下文的示例（假设禁用了“自动引用”属性，并且除了每种情况所描述的内容之外没有其他 API 更改）：

主要、次要或补丁：其他更改

您可以更改对任何发布版本中的包管理器、构建管道、脚本管道或资产数据库没有特殊影响的包清单属性。这包括更改描述、类别、关键字或 displayName。

如果更改这些字段，则可能表明您的更改不仅仅涉及错误修复。始终考虑新版本中的其他更改是否实际上需要新的 MINOR 或 MAJOR 版本，而不是 PATCH 版本。

注意：对包清单中的 unity 或 unityRelease 属性的更改始终需要 MINOR 或 MAJOR 版本。尽管这些属性不会影响包 API 本身，但增加 Unity 版本会排除包版本在以前的 Unity 编辑器上工作，并且可能会破坏依赖项目或包。降低 Unity 版本会使该包可供较旧的 Unity 编辑器使用。

已弃用和过时的 API

如果要从 API 中删除某些功能，请先发布至少一个包含弃用的次要版本。这会警告用户即将删除，以便他们可以顺利过渡到新 API。然后，您可以在新的 MAJOR 版本中删除该功能。

如果其他开发人员使用警告将包标记为过时，并且您在项目中启用了“警告”作为“错误”，则从技术上讲，过时的包可能会破坏您的项目，即使它不是真正的中断，因为代码仍然像以前一样工作。

在这种情况下，您可以选择如何修复警告即错误（按典型期望降序）：

• 更改代码，以便不再使用 API。
• 将使用 API 的代码包装在#pragma warning指令以静音警告。
• 禁用警告 CS0612 （已过时） 和 CS0618 （已过时，并显示消息） 。
• 在项目中禁用 警告（Warnings as Errors） 。