Compartilhar via


Contribuindo com o MRTK3

O MRTK3 é um projeto de código aberto sob a licença MIT. As contribuições da comunidade são bem-vindas e apreciadas, tanto para novos recursos quanto para correções de bugs.

É fácil contribuir com o MRTK3. É recomendável usar o projeto do MRTKDevTemplate Unity como um testbed de desenvolvimento conveniente, pois ele já inclui todos os pacotes MRTK3 como dependências locais no disco. Para mais informações, confira 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. Crie fork do repositório do MRTK em sua conta do GitHub.

  2. Clone seu repositório do MRTK bifurcado seguindo nosso guia sobre como iniciar de um projeto de modelo Verifique se você tem as ferramentas necessárias, especialmente a versão correta do Unity. Para garantir que você esteja no branch certo, clone usando o comando:

git clone --branch mrtk3 YOUR_GIT_URL
  1. Crie um branch para suas alterações ou correções.
git checkout -b yourchange_fix
  1. Abra o projeto de modelo MRTKDevTemplate localizado em UnityProjects/MRTKDevTemplate. Você pode adicionar o projeto ao Hub do Unity para facilitar o acesso.

  2. Faça as alterações desejadas e crie testes de unidade que garantam que as alterações funcionem conforme o esperado. Teste no editor e implantado no dispositivo. Faça o commit das alterações no seu branch. Publique seu branch no fork upstream.

  3. Abra uma solicitação de pull no repositório do MRTK, direcionando ao branch mrtk3. Descreva com precisão as alterações feitas e aplique rótulos relevantes à sua solicitação de pull para melhor categorização e triagem. Se você for um novo colaborador do MRTK, talvez seja necessário assinar nosso contrato de contribuição.

  4. Resolva as correções solicitadas pela comunidade ou pela equipe de manutenção e mescle sua PR após a aprovação.

Escrever testes

Os testes são uma parte crítica para garantir que o MRTK seja uma base confiável para aplicativos de realidade misturada de alta qualidade. Todos os novos recursos adicionados devem ter testes de unidade para garantir que a funcionalidade permaneça correta à medida que outras alterações forem feitas na base de código no futuro.

Para escrever testes de unidade, recomendamos que você primeiro examine os testes de unidade existentes e saiba como os utilitários de teste e o simulador do MRTK são usados para simular a entrada XR. Você pode simular a entrada das mãos, o foco, a posição do HMD e outros recursos básicos relacionados à entrada. Veja alguns conselhos gerais para escrever bons testes de unidade:

  • Tente escrever testes mais granulares que avaliam partes menores de funcionalidade, em vez de testes monolíticos maiores. Testes de unidade mais granulares permitem que os responsáveis pela manutenção vejam qual recurso específico foi danificado. Testes de funcionalidade de ponta a ponta mais gerais também são apreciados, mas certifique-se de que cada parte menor do seu recurso seja bem testada para começar.
  • O teste (e seu recurso) não deve fazer suposições sobre a orientação ou o local do usuário. Seus testes e recursos devem funcionar em qualquer deslocamento arbitrário ou rotação em relação à origem do mundo.
  • Se os testes simulam a entrada do usuário, use a subclasse do nosso BaseRuntimeInputTests, o que garante que o agente de teste adequado seja configurado e derrubado.
  • Use a parametrização NUnit para aumentar facilmente a variedade e a flexibilidade do teste. Confira a documentação para testes NUnit parametrizados aqui.
  • Algumas entradas ou interações podem necessitar de vários quadros para serem registradas. Você poderá usar yield return RuntimeTestUtilities.WaitForUpdates() para adicionar quadros adicionais ao teste se suas interações não estiverem sendo registradas.
  • Tente escrever testes de unidade que sejam executados o mais rápido possível para evitar tempos de iteração de CI lentos.
  • Adicione as dependências de teste relevantes ao package.json e as referências corretas ao arquivo de definição de assembly da pasta de teste.

Integração contínua

Toda solicitação de pull está sujeita a testes automatizados antes de poder ser mesclada. Outros trabalhos de CI (integração contínua) também são executados no commit resultante no branch de desenvolvimento principal para garantir que os pacotes danificados não sejam implantados no feed.

Se os testes forem aprovados no editor, mas falharem na execução de CI, você deverá executar os testes localmente no modo de lote. Alguns tipos de testes podem falhar inesperadamente ao serem executados no modo de lote sem elementos gráficos devido a diferenças de tempo ou outras peculiaridades do Unity. Executar os testes localmente no modo de lote ajuda a identificar esses testes inconsistentes antes da CI.

Use o script Tooling/Tests/run_playmode_tests.ps1 para executar testes localmente no modo de lote. Você precisará fechar seu editor do Unity para fazer isso.

$ ./Tooling/Tests/run_playmode_tests.ps1

O script gerará arquivos de saída na pasta /out, incluindo ambos os arquivos .log, bem como o .xml dos resultados de teste. Você pode filtrar os testes que são executados passando uma expressão regular para o script. Versões personalizadas do Unity e locais de pasta de projeto também podem ser fornecidos como argumentos.

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