实验性功能 - MRTK2

  • 项目

MRTK 团队开发的一些功能似乎具有很大的初始价值（即使我们还没有完全充实细节）。 对于这些类型的功能，我们希望社区有机会尽早看到它们。 由于它们处于周期的早期，因此我们将它们标记为实验性功能，以表明它们仍在不断发展，并且会随着时间的推移而改变。

实验性功能的预期结果

如果组件被标记为实验性组件，可预期以下结果：

  • 演示用法的示例场景，位于 MRTK/Examples/Experimental 子文件夹下
  • 实验性功能可能没有文档。
  • 它们可能没有测试。
  • 实验性功能可能会更改。

实验性功能指南

实验性代码应保存在一个单独的文件夹中

实验性代码应进入后跟实验性功能名称的顶层实验文件夹。 例如，如果尝试提供新功能 FooBar，将代码放入以下位置：

  • 示例场景和脚本进入 MRTK/Examples/Experimental/FooBar/
  • 组件脚本和预制件进入 MRTK/SDK/Experimental/FooBar/
  • 组件检查器进入 MRTK/SDK/Inspectors/Experimental/FooBar

使用实验性功能名称下的子文件夹时，尽量镜像 MRTK 的相同文件夹结构。

例如，求解器将进入 MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs 下

将场景保存在靠近顶部的场景文件夹中：MRTK/Examples/Experimental/FooBar/Scenes/FooBarExample.unity

注意

我们考虑不使用一个实验性根文件夹，而是将实验性文件夹放在 MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity 下。 我们决定使用底部的文件夹，以使实验性功能更易于发现。

实验性代码应包含特殊命名空间中

确保实验性代码位于与非实验性位置匹配的实验性命名空间中。 例如，如果组件是 Microsoft.MixedReality.Toolkit.Utilities.Solvers 处的求解器的一部分，则其命名空间应为 Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers。

有关示例，请参阅此 PR。

实验性功能应具有 [Experimental] 特性

在其中一个字段上方添加 [Experimental] 特性，组件编辑器中会出现一个小对话框，其中提到你的功能是实验性功能，可能会发生重大变化。

向编辑器中的菜单添加命令时，确保实验性功能位于“实验性”子菜单下。 以下是一些示例：

添加顶级菜单命令：

[MenuItem("Mixed Reality Toolkit/Experimental/MyCommand")]
public static void MyCommand()

添加组件菜单：

[AddComponentMenu("MRTK/Experimental/MyCommand")]

文档

按照以下步骤为实验性功能添加文档：

  1. 实验性功能的任何文档都应放在实验性文件夹的 readme.md 文件中。 例如 MRTK/SDK/Experimental/PulseShader/readme.md。

  2. 在“功能概述”下，在 Documentation/toc.yml 的“实验性”部分添加一个链接。

尽量减少对 MRTK 代码的影响

虽然 MRTK 更改可能会使试验正常工作，但它可能会以你意想不到的方式影响其他用户。 对 MRTK 核心代码进行的任何回归都会导致拉取请求被还原。

目标是除了实验性文件夹以外的文件夹中没有变化。 下面是可进行实验性更改的文件夹列表：

  • MRTK/SDK/Experimental
  • MRTK/SDK/Inspectors/Experimental
  • MRTK/Examples/Experimental

应谨慎处理这些文件夹之外的更改。 如果实验性功能必须包括对 MRTK 核心代码的更改，请考虑将 MRTK 更改拆分为一个包含测试和文档的单独拉取请求。

使用实验性功能不应影响用户使用核心控件的能力

大多数用户经常使用核心 UX 组件，如按钮、ManipulationHandler 和 Interactable。 如果实验性功能阻止他们使用按钮，他们很可能不会使用该实验性功能。

使用你的组件不应中断按钮、ManipulationHandler、BoundingBox 或 Interactable。

例如，在此 ScrollableObjectCollection PR 中，添加 ScrollableObjectCollection 会导致用户无法使用 HoloLens 按钮预制件。 即使这不是由 PR 中的错误引起的（而是暴露了一个现有的错误），它也阻止了 PR 被签入。

提供演示如何使用功能的示例场景

用户需要了解如何使用你的功能，以及如何测试它。

在 MRTK/Examples/Experimental/YOUR_FEATURE 下提供一个示例

最大程度地减少实验性功能中的用户可见缺陷

如果实验性功能不起作用，其他人将不会使用它，它也就不会升级成为一项功能。

在目标平台上测试示例场景，确保它正常工作。 确保功能在编辑器中也正常工作，这样用户即使没有目标平台也能快速迭代并查看功能。

将实验性代码升级为 MRTK 代码

如果某个功能最终被大量使用，则我们应该将其升级为核心 MRTK 代码。 为此，该功能应具有测试、文档和示例场景。

准备好对 MRTK 功能进行升级时，请创建一个问题以针对其签入 PR。 PR 应包括使此功能成为核心功能所需的全部内容：测试、文档和显示用法的示例场景。

此外，不要忘记更新命名空间以删除“实验性”子空间。