Экспериментальные функции — MRTK2

Некоторые функции, над которыми работает команда MRTK, имеют большую начальную ценность, даже если мы не полностью проработали детали. Мы хотим, чтобы сообщество получило возможность увидеть эти функции как можно быстрее. Поскольку они находятся в начале цикла, мы обозначаем их как экспериментальные, чтобы указать, что они по-прежнему развиваются, и подвержены изменению с течением времени.

Чего ожидать от экспериментальной функции

Если компонент помечен как экспериментальный, можно ожидать следующее:

  • Пример сцены, демонстрирующей использование, расположенную во MRTK/Examples/Experimental вложенной папке
  • Экспериментальные функции могут не иметь документации.
  • У них, вероятно, нет тестов.
  • Экспериментальные функции могут быть изменены.

Рекомендации по экспериментальным функциям

Экспериментальный код должен находиться в отдельной папке

Экспериментальный код должен перейти в папку верхнего уровня 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

Примечание

Мы рассмотрели вопрос о том, что у нас нет ни одной корневой папки Experimental, а вместо этого поместили Экспериментальный в поле .MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity Мы решили использовать папки на базе, чтобы упростить обнаружение экспериментальных функций.

Экспериментальный код должен находиться в специальном пространстве имен

Убедитесь, что экспериментальный код находится в экспериментальном пространстве имен, соответствующем не экспериментальной папке. Например, если компонент является частью решателей в Microsoft.MixedReality.Toolkit.Utilities.Solvers, его пространство имен должно иметь значение Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers.

Пример см. в этом запросе на вытягивание .

Экспериментальные функции должны иметь атрибут [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 на отдельный запрос на вытягивание, включающий тесты и документацию.

Использование экспериментальной функции не должно влиять на способность пользователей использовать основные элементы управления

Большинство пользователей очень часто используют основные компоненты пользовательского интерфейса, такие как кнопка, ManipulationHandler и Interactable. Скорее всего, они не будут использовать экспериментальную функцию, если она не позволит им использовать кнопки.

Использование компонента не должно прерывать работы кнопок, ManipulationHandler, BoundingBox или взаимодействия.

Например, в этом запросе ScrollableObjectCollection добавление ScrollableObjectCollection привело к тому, что пользователи не смогут использовать заготовки кнопки HoloLens. Несмотря на то, что это не было вызвано ошибкой в запросе на вытягивание (а, скорее, обнажило существующую ошибку), это предотвратило регистрацию запроса на вытягивание.

Предоставление примера сцены, демонстрирующей использование функции

Люди необходимо узнать, как использовать функцию и как протестировать ее.

Укажите пример в разделе MRTK/Examples/Experimental/YOUR_FEATURE

Минимизация видимых пользователем недостатков в экспериментальных функциях

Другие не будут использовать экспериментальную функцию, если она не работает, она не будет перейти к функции.

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

Окончание экспериментального кода в код MRTK

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

Когда вы будете готовы к выпуску функции MRTK, создайте проблему, чтобы проверка в запросе на вытягивание. Запрос на вытягивание должен включать в себя все, что необходимо для того, чтобы сделать эту основную функцию: тесты, документацию и пример сцены, показывающую использование.

Кроме того, не забудьте обновить пространства имен, чтобы удалить подпространство "Experimental".