Recursos experimentais — MRTK2

Alguns recursos nos quais a equipe do MRTK trabalha parecem ter um grande valor inicial, ainda que não tenhamos completado os detalhes. Para esses tipos de recursos, queremos que a comunidade tenha a chance de vê-los antecipadamente. Como eles estão no início do ciclo, os rotulamos como experimentais para indicar que eles ainda estão evoluindo e sujeitos a alterações ao longo do tempo.

O que esperar de um recurso experimental

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

• Uma cena de exemplo que demonstra o uso, localizada em MRTK/Examples/Experimental subpasta
• Os recursos experimentais podem não ter documentos.
• Eles provavelmente 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 entram em MRTK/Examples/Experimental/FooBar/
• Scripts de componente, pré-fabricados vão para MRTK/SDK/Experimental/FooBar/
• Inspetores de componentes entram MRTK/SDK/Inspectors/Experimental/FooBar

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

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

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

Observação

Consideramos não ter uma única pasta raiz experimental e, em vez disso, colocar Experimental em digamos MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity. Decidimos ir com 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 corresponda ao local não experimental. Por exemplo, se o componente fizer parte dos solucionadores em Microsoft.MixedReality.Toolkit.Utilities.Solvers, seu namespace deverá ser Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers.

Consulte esta PR para obter 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.

Os menus para recursos experimentais devem estar no submenu "Experimental"

Verifique se os recursos experimentais estão em submenus "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 documentação para seu recurso experimental:

1. Qualquer documentação de um recurso experimental deve ser usada 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. Quaisquer regressões que você fizer ao código principal do MRTK resultariam na reversão da solicitação de pull.

Procure não ter nenhuma alteração em pastas diferentes de pastas experimentais. Aqui está uma lista de pastas que podem ter alterações experimentais:

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

As alterações fora dessas pastas devem ser tratadas com muito cuidado. Se o recurso experimental precisar incluir alterações no código principal do MRTK, considere dividir as alterações do MRTK em uma solicitação de pull separada que inclua 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 principais da experiência do usuário, como o botão, ManipulationHandler e Interactable com muita frequência. Eles provavelmente não usarão seu recurso experimental se ele os impedir de usar botões.

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

Por exemplo, nesta PR ScrollableObjectCollection, a adição de um ScrollableObjectCollection fez com que as pessoas não conseguissem usar os pré-fabricados do botão 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.

Fornecer uma cena de exemplo que demonstra como usar o recurso

Pessoas precisa 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 se formará em um recurso.

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

Graduando código experimental em código MRTK

Se um recurso acabar vendo bastante uso, devemos formá-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 recurso MRTK, crie um problema para marcar em sua PR. A PR deve incluir todas as coisas necessárias para tornar esse 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".