通过

对 MRTK3 做出贡献

MRTK3 是 MIT 许可下的开源项目。 我们非常欢迎并感激对社区做出贡献的行为，无论是针对新功能还是 bug 修复。

对 MRTK3 做出贡献非常简单。 建议将 MRTKDevTemplate Unity 项目用作方便的开发测试点，因为它已将所有 MRTK3 包作为本地磁盘上依赖项包含在内。 有关详细信息，请参阅有关 MRTKDevTemplate 项目的文档以详细了解示例场景和本地磁盘上依赖项。

贡献指南

  1. 面向 GitHub 帐户创建 MRTK 存储库分支。

  2. 按照我们在从模板项目开始上的指南克隆你的分支 MRTK 存储库。确保你有所需的工具，尤其是正确的 Unity 版本。 若要确保位于正确的分支上，请使用命令进行克隆：

git clone --branch mrtk3 YOUR_GIT_URL
  1. 为更改或修复创建新分支。
git checkout -b yourchange_fix

  1. 打开位于 UnityProjects/MRTKDevTemplate 中的 MRTKDevTemplate 模板项目。 可以将项目添加到 Unity Hub 以便于访问。

  2. 进行所需的更改并创建单元测试，以确保更改按预期正常工作。 确保跨编辑器进行测试并部署到设备。 将更改提交到分支。 将分支发布到上游分支。

  3. 在面向 mrtk3 分支的 MRTK 存储库上打开拉取请求。 确保准确描述所做的更改，并将相关标签应用于拉取请求，以便更好地进行分类和会审。 如果你是 MRTK 的新贡献者，则可能需要签署我们的贡献协议。

  4. 解决社区或维护团队请求的任何修补程序，并在批准后合并 PR。

编写测试

测试是确保 MRTK 成为高质量混合现实应用程序的可靠基础的关键部分。 添加的任何新功能都应进行单元测试，以确保其功能在将来对代码库进行其他更改时保持正确。

若要编写单元测试，建议首先查看现有的单元测试，并了解如何使用 MRTK 测试实用工具和模拟器来模拟 XR 输入。 可以模拟手部输入、凝视、HMD 位置和其他基本输入相关功能。 下面是编写良好单元测试的一些一般建议：

  • 请尝试编写更精细的测试来评估较小的功能部分，而不是更大的整体测试。 更精细的单元测试允许维护者查看哪个特定功能被破坏了。 更常规的端到端功能测试也值得赞赏，但请确保功能的每个较小部分都经过良好测试，以便从头开始。
  • 确保测试（和功能）不会对用户的方向或位置做出任何假设。 测试和功能应在与世界原点的任何任意偏移或旋转下工作。
  • 如果测试模拟用户输入，请确保将对我们的 BaseRuntimeInputTests 进行子类化，这可确保设置和拆除正确的测试工具。
  • 使用 NUnit 参数化轻松增加测试的多样性和灵活性。 请参阅此处有关参数化 NUnit 测试的文档。
  • 某些输入或交互可能需要多个帧进行注册。 如果你的交互未注册，则可以使用 yield return RuntimeTestUtilities.WaitForUpdates() 向你的测试添加额外的延迟帧。
  • 尝试编写尽快执行的单元测试，以避免 CI 迭代速度缓慢。
  • 请确保将相关的测试依赖项添加到 package.json，将正确的引用添加测试文件夹的程序集定义文件。

持续集成

每个拉取请求在能够合并之前都需要经过自动化测试。 其他持续集成 (CI) 作业也会在主开发分支上生成的提交上运行，以确保损坏的包不会部署到源。

如果测试在编辑器中通过，但在 CI 运行中失败，则应在批处理模式下本地运行测试。 在无图形批处理模式下运行时，由于计时差异或其他 Unity 特殊行为，某些类型的测试可能会意外失败。 在批处理模式下本地运行测试有助于在 CI 之前识别这些不一致的测试。

使用 Tooling/Tests/run_playmode_tests.ps1 脚本在批处理模式下本地运行测试。 需要关闭 Unity 编辑器才能执行此操作。

$ ./Tooling/Tests/run_playmode_tests.ps1

该脚本将在 /out 文件夹中生成输出文件，包括 .log 文件和测试结果 .xml。 可以通过将正则表达式传递给脚本来筛选要运行的测试。 自定义 Unity 版本和项目文件夹位置也可以作为参数提供。

$ ./Tooling/Tests/run_playmode_tests.ps1 -unityVersion 2021.3.5f1 -projectPath ../my/project/path