실험적 기능 - 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] 필드 중 하나 위에 특성을 추가하여 기능이 실험적이며 상당한 변경이 발생할 수 있음을 언급하는 작은 대화 상자가 구성 요소 편집기에서 나타납니다.

편집기에서 메뉴에 명령을 추가할 때 실험적 기능이 "실험적" 하위 메뉴 아래에 있는지 확인합니다. 다음은 몇 가지 예입니다.

최상위 메뉴 명령 추가:

[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 코어 코드에 대한 회귀로 인해 끌어오기 요청이 되돌려질 수 있습니다.

실험적 폴더가 아닌 폴더에 변경 내용이 0개 있는 것을 목표로 합니다. 실험적 변경이 있을 수 있는 폴더 목록은 다음과 같습니다.

  • MRTK/SDK/실험적
  • MRTK/SDK/Inspectors/실험적
  • MRTK/예제/실험적

이러한 폴더 외부의 변경 내용은 매우 신중하게 처리해야 합니다. 실험적 기능에 MRTK 핵심 코드 변경 내용이 포함되어야 하는 경우 MRTK 변경 내용을 테스트 및 설명서를 포함하는 별도의 끌어오기 요청으로 분할하는 것이 좋습니다.

실험적 기능을 사용하는 것은 핵심 컨트롤을 사용하는 사람들의 능력에 영향을 미치지 않아야 합니다.

대부분의 사람들은 단추, ManipulationHandler 및 상호 작용과 같은 핵심 UX 구성 요소를 매우 자주 사용합니다. 단추를 사용할 수 없으면 실험적 기능을 사용하지 않을 수 있습니다.

구성 요소를 사용하면 단추, ManipulationHandler, BoundingBox 또는 상호 작용이 중단되지 않아야 합니다.

예를 들어 이 ScrollableObjectCollection PR에서 ScrollableObjectCollection을 추가하면 사용자가 HoloLens 단추 프리팹을 사용할 수 없게 됩니다. PR의 버그로 인한 것이 아니라 기존 버그를 노출했음에도 불구하고 PR이 체크 인되지 않았습니다.

기능을 사용하는 방법을 보여 주는 예제 장면 제공

사람들은 기능을 사용하는 방법과 테스트 방법을 확인해야 합니다.

MRTK/Examples/Experimental/YOUR_FEATURE 아래에 예제를 제공합니다.

실험적 기능에서 사용자에게 표시되는 결함 최소화

다른 사람들은 실험적 기능이 작동하지 않으면 사용하지 않으며 기능으로 졸업하지 않습니다.

대상 플랫폼에서 예제 장면을 테스트하고 예상대로 작동하는지 확인합니다. 사용자가 대상 플랫폼이 없더라도 기능을 빠르게 반복하고 볼 수 있도록 기능이 편집기에서도 작동하는지 확인합니다.

실험 코드를 MRTK 코드로 졸업

기능이 상당히 많이 사용되면 핵심 MRTK 코드로 졸업해야 합니다. 이렇게 하려면 기능에 테스트, 설명서 및 예제 장면이 있어야 합니다.

기능 MRTK를 졸업할 준비가 되면 PR을 확인하는 문제를 만듭니다. PR에는 테스트, 설명서 및 사용량을 보여 주는 예제 장면과 같은 핵심 기능을 만드는 데 필요한 모든 항목이 포함되어야 합니다.

또한 "실험적" 하위 영역을 제거하도록 네임스페이스를 업데이트해야 합니다.