Recursos experimentais

Alguns recursos em que a equipe do MRTK trabalha parecem ter muito valor inicial, mesmo que ainda não tenhamos completado os detalhes. Para esses tipos de recursos, queremos que a comunidade receba a oportunidade de vê-los mais cedo. Como eles estão no início do ciclo, os rotularemos como experimentais para indicar que ainda estão evoluindo e sujeitos a alterações ao longo do tempo.

O que esperar de um recurso experimental

Se um componente for marcado como experimental, você poderá esperar o seguinte:

  • Uma cena de exemplo que demonstra o uso, localizada na MRTK/Examples/Experimental sub pasta
  • Os recursos experimentais podem não ter documentos.
  • Provavelmente, eles não têm testes.
  • Os recursos experimentais estão sujeitos a alterações.

Diretrizes de recursos experimentais

O código experimental deve residir em uma pasta separada

O código experimental deve entrar em uma pasta experimental de nível superior seguida pelo nome do recurso experimental. Por exemplo, se estiver tentando contribuir com um novo recurso FooBar, coloque o código no seguinte:

  • Cenas de exemplo, os scripts vão para MRTK/Examples/Experimental/FooBar/
  • Scripts de componente, pré-requisitos para MRTK/SDK/Experimental/FooBar/
  • Os inspetores de componentes vão para MRTK/SDK/Inspectors/Experimental/FooBar

Ao usar sub pastas sob o nome do recurso experimental, tente espelhar a mesma estrutura de pastas do MRTK.

Por exemplo, os solucionadores entrariam em MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs

Mantenha cenas em uma pasta de cena perto da parte superior: MRTK/Examples/Experimental/FooBar/Scenes/FooBarExample.unity

Observação

Considerámos não ter uma única pasta raiz experimental e, em vez disso, colocar Experimental em digamos MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity. Decidimos usar pastas na base para facilitar a descoberta dos recursos experimentais.

O código experimental deve estar em um namespace especial

Verifique se o código experimental reside em um namespace experimental que corresponde ao local não experimental. Por exemplo, se o componente faz parte dos solucionadores em Microsoft.MixedReality.Toolkit.Utilities.Solvers, seu namespace deve ser Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers.

Consulte esta PR para ver um exemplo.

Os recursos experimentais devem ter um atributo [Experimental]

Adicione um [Experimental] atributo acima de um de seus campos para que uma pequena caixa de diálogo apareça no editor de componentes que menciona que seu recurso é experimental e está sujeito a alterações significativas.

Verifique se os recursos experimentais estão em sub-menus "experimentais" ao adicionar comandos aos menus no editor. Veja alguns exemplos:

Adicionando um comando de menu de nível superior:

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

Adicionando um menu de componente:

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

Documentação

Siga estas etapas para adicionar a documentação do recurso experimental:

  1. Qualquer documentação para um recurso experimental deve estar em um readme.md arquivo na pasta experimental. Por exemplo, MRTK/SDK/Experimental/PulseShader/readme.md.

  2. Em Visão geral do recurso , adicione um link na seção Experimental em Documentation/toc.yml.

Minimizar o impacto no código do MRTK

Embora a alteração do MRTK possa fazer com que seu experimento funcione, isso pode afetar outras pessoas de maneiras que você não espera. As regressões que você fizer ao código principal do MRTK resultariam na reversão da solicitação de pull.

O objetivo é ter zero alterações em pastas que não são experimentais. Aqui está uma lista de pastas que podem ter alterações experimentais:

  • MRTK/SDK/Experimental
  • MRTK/SDK/Inspetores/Experimental
  • MRTK/Examples/Experimental

As alterações fora dessas pastas devem ser tratadas com muito cuidado. Se o recurso experimental deve incluir alterações no código principal do MRTK, considere dividir as alterações do MRTK em uma solicitação pull separada que inclui testes e documentação.

Usar seu recurso experimental não deve afetar a capacidade das pessoas de usar controles principais

A maioria das pessoas usa componentes de experiência do usuário principais, como o botão ManipulationHandler e o Interactable, com muita frequência. Provavelmente, eles não usarão seu recurso experimental se impedirem o uso de botões.

O uso do componente não deve quebrar botões, ManipulationHandler, BoundingBox ou interaja.

Por exemplo, nesta PR ScrollableObjectCollection, adicionar um ScrollableObjectCollection fez com que as pessoas não fosse capazes de usar os pré-HoloLens botão de HoloLens. Embora isso não tenha sido causado por um bug na PR (mas, em vez disso, expôs um bug existente), ele impediu que a PR fosse verificada.

Forneça uma cena de exemplo que demonstra como usar o recurso

As pessoas precisam ver como usar seu recurso e como testá-lo.

Forneça um exemplo em MRTK/Examples/Experimental/YOUR_FEATURE

Minimizar falhas visíveis do usuário em recursos experimentais

Outros não usarão o recurso experimental se ele não funcionar, ele não será formado para um recurso.

Teste sua cena de exemplo em sua plataforma de destino, certifique-se de que ela funciona conforme o esperado. Certifique-se de que seu recurso também funcione no editor, para que as pessoas possam iterar rapidamente e ver seu recurso, mesmo que não tenham a plataforma de destino.

Como transformar código experimental em código MRTK

Se um recurso acabar vendo muita utilização, devemos agredá-lo no código principal do MRTK. Para fazer isso, o recurso deve ter testes, documentação e uma cena de exemplo.

Quando você estiver pronto para formar o MRTK do recurso, crie um problema para verificar sua PR. A PR deve incluir todas as coisas necessárias para tornar isso um recurso principal: testes, documentação e uma cena de exemplo mostrando o uso.

Além disso, não se esqueça de atualizar os namespaces para remover o subespaço "Experimental".