Funcionalidades experimentais — MRTK2

Algumas funcionalidades em que a equipa do MRTK trabalha parecem ter muito valor inicial, mesmo que ainda não tenhamos completado os detalhes. Para este tipo de funcionalidades, queremos que a comunidade consiga vê-las mais cedo. Uma vez que estão no início do ciclo, rotulamo-los como experimentais para indicar que ainda estão a evoluir e sujeitos a mudanças ao longo do tempo.

O que esperar de uma funcionalidade experimental

Se um componente for marcado como experimental, pode esperar o seguinte:

• Uma cena de exemplo que demonstra a utilização, localizada em MRTK/Examples/Experimental subpasta
• As funcionalidades experimentais podem não ter documentos.
• Provavelmente não têm testes.
• As funcionalidades experimentais estão sujeitas a alterações.

Diretrizes experimentais de funcionalidades

O código experimental deve estar numa pasta separada

O código experimental deve entrar numa pasta experimental de nível superior, seguida do nome da funcionalidade experimental. Por exemplo, se tentar contribuir com uma nova funcionalidade fooBar, coloque o código no seguinte:

• Cenas de exemplo, scripts entram em MRTK/Examples/Experimental/FooBar/
• Scripts de componentes, pré-fabricados entram em MRTK/SDK/Experimental/FooBar/
• Os inspetores de componentes entram em MRTK/SDK/Inspectors/Experimental/FooBar

Ao utilizar subpastas sob o nome da funcionalidade experimental, tente espelhar a mesma estrutura de pastas do MRTK.

Por exemplo, os solucionadores iriam para baixo MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs

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

Nota

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

O código experimental deve estar num espaço de nomes especial

Certifique-se de que o código experimental reside num espaço de nomes experimental que corresponda à localização não experimental. Por exemplo, se o componente fizer parte dos solucionadores em Microsoft.MixedReality.Toolkit.Utilities.Solvers, o respetivo espaço de nomes deve ser Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers.

Veja este PR para obter um exemplo.

As funcionalidades experimentais devem ter um atributo [Experimental]

Adicione um [Experimental] atributo acima de um dos campos para que seja apresentada uma caixa de diálogo pequena no editor de componentes que menciona que a sua funcionalidade é experimental e está sujeita a alterações significativas.

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

Certifique-se de que as funcionalidades experimentais estão em submenus "experimentais" ao adicionar comandos a menus no editor. Eis alguns exemplos:

Adicionar um comando de menu de nível superior:

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

Adicionar um menu de componentes:

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

Documentação

Siga estes passos para adicionar documentação para a sua funcionalidade experimental:

1. Qualquer documentação para uma funcionalidade experimental deve ser apresentada num readme.md ficheiro na pasta experimental. Por exemplo, MRTK/SDK/Experimental/PulseShader/readme.md.

2. Em Descrições Gerals de Funcionalidades , adicione uma ligação na secção Experimental em Documentation/toc.yml.

Minimizar o impacto no código MRTK

Embora a alteração do MRTK possa fazer com que a sua experimentação funcione, pode afetar outras pessoas de formas que não espera. Todas as regressões que fizer ao código principal do MRTK resultarão na reversão do pedido Pull.

O objetivo é ter zero alterações em pastas que não sejam pastas experimentais. Eis uma lista de pastas que podem ter alterações experimentais:

• MRTK/SDK/Experimental
• MRTK/SDK/Inspetores/Experimental
• MRTK/Exemplos/Experimental

As alterações fora destas pastas devem ser tratadas com muito cuidado. Se a funcionalidade experimental tiver de incluir alterações ao código principal do MRTK, considere dividir as alterações do MRTK num pedido Pull separado que inclua testes e documentação.

A utilização da funcionalidade experimental não deve afetar a capacidade das pessoas de utilizarem controlos principais

A maioria das pessoas utiliza componentes principais de UX como o botão ManipulationHandler e Interactable com muita frequência. É provável que não utilizem a sua funcionalidade experimental se esta impedir que utilizem botões.

A utilização do componente não deve interromper botões, ManipulationHandler, BoundingBox ou interagiveis.

Por exemplo, neste PR ScrollableObjectCollection, adicionar um ScrollableObjectCollection fez com que as pessoas não pudessem utilizar os pré-fabricados do botão HoloLens. Apesar de este erro não ter sido causado por um erro no PR (mas, em vez disso, ter exposto um erro existente), impediu que o PR fosse verificado.

Fornecer um cenário de exemplo que demonstra como utilizar a funcionalidade

Pessoas precisar de ver como utilizar a funcionalidade e como testá-la.

Indique um exemplo em MRTK/Examples/Experimental/YOUR_FEATURE

Minimizar falhas visíveis do utilizador em funcionalidades experimentais

Outros não utilizarão a funcionalidade experimental se não funcionar, não se formarão numa funcionalidade.

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

Formar código experimental em código MRTK

Se uma funcionalidade acabar por ser bastante utilizada, então devemos formá-la em código MRTK principal. Para tal, a funcionalidade deve ter testes, documentação e um cenário de exemplo.

Quando estiver pronto para formar a funcionalidade MRTK, crie um problema para dar entrada do seu PEDIDO Pull. O PR deve incluir todas as coisas necessárias para tornar esta funcionalidade principal: testes, documentação e uma cena de exemplo que mostre a utilização.

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