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

Некоторые функции, на которых работает команда МРТК, имеют большое значение, даже если мы не полностью создали подробные сведения. Для этих типов функций мы хотим, чтобы сообщество познакомиться с ними на раннем этапе. Так как они находятся на раннем этапе цикла, мы помечаем их как экспериментальные, чтобы указать, что они продолжают развиваться и могут меняться со временем.

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

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

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

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

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

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

  • Примеры сцен, переходы по сценариям MRTK/Examples/Experimental/FooBar/
  • Скрипты компонентов, Prefabs MRTK/SDK/Experimental/FooBar/
  • Переходят инспекторы компонентов MRTK/SDK/Inspectors/Experimental/FooBar

При использовании вложенных папок в имени экспериментальной функции попробуйте создать зеркальную копию той же структуры папок МРТК.

Например, поисковые решения будут выглядеть по адресу 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 .

Пример см. в этой статье.

Экспериментальные функции должны иметь атрибут [экспериментальный]

Добавьте [Experimental] атрибут над одним из полей, чтобы в редакторе компонентов отображалось небольшое диалоговое окно, в котором упоминается ваша функция, которая подвергается значительным изменениям.

Убедитесь, что экспериментальные функции находятся в подменю "экспериментальные" при добавлении команд в меню редактора. Вот несколько таких случаев.

Добавление команды меню верхнего уровня:

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

Добавление меню компонента:

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

Документация

Чтобы добавить документацию для экспериментальной функции, выполните следующие действия.

  1. Любая документация для экспериментальной функции должна находиться в readme.md файле в экспериментальной папке. Например, МРТК/SDK/экспериментальный/Пулсешадер/readme. md.

  2. В разделе обзоры функций добавьте ссылку в экспериментальном разделе по адресу Documentation/toc.yml .

Уменьшение влияния на код МРТК

В то время как изменение МРТК может повлиять на работу вашего эксперимента, оно может оказать влияние на других людей. Любые регрессии, вносимые в основной код МРТК, приведут к возврату запроса на включение внесенных изменений.

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

  • МРТК/SDK/экспериментальная версия
  • МРТК/SDK/инспекторы/экспериментальные
  • МРТК/примеры/экспериментальные

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

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

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

Использование компонента не должно прерывать кнопки, Манипулатионхандлер, BoundingBox или взаимодействовать.

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

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

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

Укажите пример в разделе МРТК/examples/экспериментальный/YOUR_FEATURE

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

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

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

Экспериментальный пример кода в код МРТК

Если функция приостанавливается на большом объеме использования, мы должны углубиться в основной код МРТК. Для этого компонент должен иметь тесты, документацию и пример сцены.

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

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