Partilhar via

Contribuir para o MRTK3

  • Artigo

O MRTK3 é um projeto open source sob a licença do MIT. As contribuições da comunidade são bem-vindas e apreciadas, tanto para novas funcionalidades como para correções de erros.

É fácil contribuir para o MRTK3. Recomendamos que utilize o projeto unity MRTKDevTemplate como um teste de desenvolvimento conveniente, uma vez que já inclui todos os pacotes MRTK3 como dependências locais no disco. Para obter mais informações, veja a documentação sobre o projeto MRTKDevTemplate para obter mais detalhes sobre cenas de exemplo e dependências locais no disco.

Guia de contribuição

  1. Fork o repositório MRTK para a sua conta do GitHub.

  2. Clone o seu repositório MRTK bifurcado ao seguir o nosso guia sobre como começar a partir de um projeto de modelo Certifique-se de que tem as ferramentas necessárias, especialmente a versão correta do Unity. Para garantir que está no ramo direito, clone com o comando:

git clone --branch mrtk3 YOUR_GIT_URL
  1. Crie um novo ramo para as suas alterações ou correções.
git checkout -b yourchange_fix

  1. Abra o projeto de MRTKDevTemplate modelo localizado em UnityProjects/MRTKDevTemplate. Pode adicionar o projeto ao Seu Hub do Unity para facilitar o acesso.

  2. Faça as alterações pretendidas e crie testes de unidades que garantam que as alterações funcionam conforme esperado. Certifique-se de que testa no editor e implementa no dispositivo. Consolide as alterações ao seu ramo. Publique o ramo no fork a montante.

  3. Abra um pedido Pull no repositório MRTK, direcionando o mrtk3 ramo. Certifique-se de que descreve com precisão as alterações efetuadas e aplica etiquetas relevantes ao seu pedido Pull para uma melhor categorização e triagem. Se for um novo contribuidor para o MRTK, poderá ter de assinar o nosso contrato de contribuição.

  4. Resolva as correções pedidas pela comunidade ou pela equipa de manutenção e intercale o seu PR após a aprovação.

Escrever testes

Os testes são uma parte fundamental para garantir que o MRTK é uma base fiável para aplicações de alta qualidade de realidade mista. Quaisquer novas funcionalidades adicionadas devem ter testes de unidades para garantir que a respetiva funcionalidade permanece correta, uma vez que outras alterações são efetuadas na base de código no futuro.

Para escrever testes de unidades, recomendamos que analise primeiro os testes de unidades existentes e saiba como os utilitários de teste e o simulador do MRTK são utilizados para simular a entrada XR. Pode simular a entrada manual, o olhar, a posição HMD e outras funcionalidades básicas relacionadas com a entrada. Eis alguns conselhos gerais para escrever bons testes de unidades:

  • Tente escrever testes mais granulares que avaliem partes mais pequenas de funcionalidade, em vez de testes monolíticos maiores. Os testes de unidades mais granulares permitem aos responsáveis pela manutenção ver que funcionalidade específica foi quebrada. Os testes de funcionalidade ponto a ponto mais gerais também são apreciados, mas certifique-se de que cada parte mais pequena da sua funcionalidade é bem testada para começar.
  • Certifique-se de que o teste (e a funcionalidade) não assume a orientação ou localização do utilizador. Os seus testes e funcionalidades devem funcionar em qualquer desvio arbitrário ou rotação da origem mundial.
  • Se os testes simularem a entrada do utilizador, certifique-se de que subclasse o nosso BaseRuntimeInputTests, o que garante que o arnês de teste adequado está configurado e demolido.
  • Utilize a parametrização NUnit para aumentar facilmente a variedade e a flexibilidade do teste. Veja a documentação para testes NUnit parametrizados aqui.
  • Algumas entradas ou interações podem demorar vários fotogramas a registar. Pode utilizar yield return RuntimeTestUtilities.WaitForUpdates() para adicionar fotogramas adicionais de atraso ao teste se as suas interações não estiverem a ser registadas.
  • Tente escrever testes de unidades que são executados o mais rapidamente possível para evitar tempos de iteração de CI lentos.
  • Certifique-se de que adiciona as dependências de teste relevantes ao package.jsone as referências corretas ao ficheiro de definição de assemblagem da pasta de teste.

Integração contínua

Todos os pedidos Pull estão sujeitos a testes automatizados antes de poderem ser intercalados. Outras tarefas de integração contínua (CI) também são executadas na consolidação resultante no ramo de desenvolvimento principal para garantir que os pacotes danificados não são implementados no feed.

Se os seus testes estiverem a passar no editor, mas falharem na execução de CI, deve executar os testes localmente no modo batch. Alguns tipos de testes podem falhar inesperadamente ao executar no modo de lote sem gráficos devido a diferenças de tempo ou outras peculiaridades do Unity. Executar os testes localmente no modo batch ajuda a identificar estes testes inconsistentes antes da CI.

Utilize o Tooling/Tests/run_playmode_tests.ps1 script para executar testes localmente no modo batch. Terá de fechar o editor do Unity para o fazer.

$ ./Tooling/Tests/run_playmode_tests.ps1

O script irá gerar ficheiros de saída na /out pasta, incluindo os .log ficheiros e os resultados .xmldo teste. Pode filtrar os testes que são executados ao transmitir uma expressão regular para o script. As versões personalizadas do Unity e as localizações das pastas do projeto também podem ser fornecidas como argumentos.

$ ./Tooling/Tests/run_playmode_tests.ps1 -unityVersion 2021.3.5f1 -projectPath ../my/project/path