Funzionalità sperimentali - MRTK2

Alcune funzionalità su cui il team MRTK lavora sembrano avere un sacco di valore iniziale, anche se i dettagli non sono stati completamente compilati. Per questi tipi di funzionalità, vogliamo che la community possa vederle presto. Poiché sono all'inizio del ciclo, le etichetteremo come sperimentali per indicare che sono ancora in evoluzione e soggette a modifiche nel tempo.

Cosa aspettarsi da una funzionalità sperimentale

Se un componente è contrassegnato come sperimentale, è possibile prevedere quanto segue:

• Scena di esempio che illustra l'utilizzo, che si trova nella MRTK/Examples/Experimental sottocartella
• Le funzionalità sperimentali potrebbero non avere documenti.
• Probabilmente non hanno test.
• Le funzionalità sperimentali sono soggette a modifiche.

Linee guida per le funzionalità sperimentali

Il codice sperimentale deve vissuto in una cartella separata

Il codice sperimentale deve essere inserito in una cartella sperimentale di primo livello seguita dal nome della funzionalità sperimentale. Ad esempio, se si tenta di contribuire a una nuova funzionalità FooBar, inserire il codice seguente:

• Scene di esempio, script vengono inseriti in MRTK/Examples/Experimental/FooBar/
• Script dei componenti, prefab vengono inseriti in MRTK/SDK/Experimental/FooBar/
• I controlli dei componenti vengono inseriti MRTK/SDK/Inspectors/Experimental/FooBar

Quando si usano sottocartelle con il nome della funzionalità sperimentale, provare a eseguire il mirroring della stessa struttura di cartelle di MRTK.

Ad esempio, i risolutori andrebbero sotto MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs

Tenere le scene in una cartella della scena nella parte superiore: MRTK/Examples/Experimental/FooBar/Scenes/FooBarExample.unity

Nota

È stata considerata la mancata presenza di una singola cartella radice sperimentale e l'inserimento di Experimental in say MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity. Abbiamo deciso di andare con le cartelle alla base per semplificare l'individuazione delle funzionalità sperimentali.

Il codice sperimentale deve trovarsi in uno spazio dei nomi speciale

Assicurarsi che il codice sperimentale si trovi in uno spazio dei nomi sperimentale corrispondente alla posizione non sperimentale. Ad esempio, se il componente fa parte dei risolutori in Microsoft.MixedReality.Toolkit.Utilities.Solvers, lo spazio dei nomi deve essere Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers.

Per un esempio, vedere questa richiesta pull .

Le funzionalità sperimentali devono avere un attributo [Sperimentale]

Aggiungere un [Experimental] attributo sopra uno dei campi per visualizzare una piccola finestra di dialogo nell'editor di componenti che indica che la funzionalità è sperimentale e soggetta a modifiche significative.

I menu per le funzionalità sperimentali devono essere inclusi nel sottomenu "Sperimentale"

Assicurarsi che le funzionalità sperimentali si trovino nei sottomenu "sperimentali" quando si aggiungono comandi ai menu nell'editor. Ecco alcuni esempi:

Aggiunta di un comando di menu di primo livello:

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

Aggiunta di un menu componente:

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

Documentazione

Seguire questa procedura per aggiungere la documentazione per la funzionalità sperimentale:

1. Qualsiasi documentazione per una funzionalità sperimentale deve essere inserita in un readme.md file nella cartella sperimentale. Ad esempio, MRTK/SDK/Experimental/PulseShader/readme.md.

2. In Cenni preliminari sulle funzionalità Aggiungere un collegamento nella sezione Sperimentale all'indirizzo Documentation/toc.yml.

Ridurre al minimo l'impatto sul codice MRTK

Anche se la modifica di MRTK potrebbe far funzionare l'esperimento, potrebbe influire sugli altri utenti in modi non previsti. Qualsiasi regressione eseguita nel codice di base MRTK comporterà il ripristino della richiesta pull.

Mirare ad avere zero modifiche nelle cartelle diverse dalle cartelle sperimentali. Ecco un elenco di cartelle che possono avere modifiche sperimentali:

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

Le modifiche al di fuori di queste cartelle devono essere trattate con molta attenzione. Se la funzionalità sperimentale deve includere modifiche al codice di base MRTK, è consigliabile suddividere le modifiche MRTK in una richiesta pull separata che include test e documentazione.

L'uso della funzionalità sperimentale non deve influire sulla capacità degli utenti di usare i controlli di base

La maggior parte delle persone usa componenti principali dell'esperienza utente come il pulsante, ManipulationHandler e Interactable molto frequentemente. Probabilmente non useranno la funzionalità sperimentale se impedisce loro di usare pulsanti.

L'uso del componente non deve interrompere pulsanti, ManipulationHandler, BoundingBox o interagire.

In questa richiesta pull ScrollableObjectCollection, ad esempio, l'aggiunta di un oggetto ScrollableObjectCollection ha causato l'impossibilità di usare i prefab del pulsante HoloLens. Anche se questo non è stato causato da un bug nella richiesta pull (ma piuttosto esposto un bug esistente), ha impedito che la richiesta pull venga archiviata.

Fornire una scena di esempio che illustra come usare la funzionalità

Persone necessario vedere come usare la funzionalità e come testarla.

Fornire un esempio in MRTK/Examples/Experimental/YOUR_FEATURE

Ridurre al minimo i difetti visibili dell'utente nelle funzionalità sperimentali

Altri non useranno la funzionalità sperimentale se non funziona, non si laureerà a una funzionalità.

Testare la scena di esempio nella piattaforma di destinazione, assicurarsi che funzioni come previsto. Assicurarsi che la funzionalità funzioni anche nell'editor, in modo che gli utenti possano eseguire rapidamente l'iterazione e visualizzare la funzionalità anche se non hanno la piattaforma di destinazione.

Laurea di codice sperimentale nel codice MRTK

Se una funzionalità finisce per vedere molto d'uso, è consigliabile laurearla in codice MRTK di base. A tale scopo, la funzionalità deve avere test, documentazione e una scena di esempio.

Quando si è pronti per laureare la funzionalità MRTK, creare un problema per archiviare la richiesta pull. La richiesta pull deve includere tutti gli elementi necessari per rendere questa funzionalità di base: test, documentazione e una scena di esempio che mostra l'utilizzo.

Inoltre, non dimenticare di aggiornare gli spazi dei nomi per rimuovere lo spazio secondario "Sperimentale".