Запросы на вытягивание — MRTK2

  • Статья

Предварительные требования

Если вы ранее не участвовали в проектах корпорации Майкрософт, вам может быть предложено подписать лицензионное соглашение с участником. Эту информацию вы можете увидеть в комментарии к запросу на вытягивание.

Важно!

Если вы являетесь сотрудником корпорации Майкрософт и не являетесь членом организации Майкрософт на GitHub, свяжите свои учетные записи Майкрософт и GitHub в корпоративной сети, посетив страницу Открытый код в Майкрософт, прежде чем инициировать запрос на вытягивание. Есть еще несколько процессов, которые вам нужно выполнить заранее.

Создание запроса на включение изменений

Когда вы будете готовы отправить запрос на вытягивание, создайте запрос на вытягивание, предназначенный для main ветви. Чтобы устранить ошибки в период стабилизации выпуска, найдите последнюю prerelease/* ветвь. Новые функции всегда должны идти в main.

Ознакомьтесь с рекомендациями и убедитесь, что ваш запрос на вытягивание соответствует им.

  • Обязательно укажите, к какой проблеме, запросу функции или задаче относится ваш запрос на вытягивание.
  • Убедитесь, что запрос на вытягивание содержит только те файлы и изменения, которые имеют прямое отношение к этому запросу.
  • Убедитесь, что в нем присутствует обновленная документация. Убедитесь, что все открытые поля содержат комментарии.
  • Если вы добавляете новую функцию, проверьте наличие тестов для проверки этой функции (см. UnitTests).
  • Если вы исправляете ошибку, напишите тест для проверки исправления ошибки.

Ваши изменения будут проверены ответственными за проект. Мы стараемся изучать все изменения в течение трех рабочих дней. Учтите все комментарии проверяющих, отправьте изменения в ветвь раздела и опубликуйте комментарий, чтобы сообщить нам о необходимости проверить новую часть кода.

Примечание

Все отправленные в проект запросы на вытягивание будут также проверяться в соответствии с руководством по стандартам кодирования MRTK. Чтобы процесс прошел беспроблемно, изучите эти стандарты, прежде чем отправлять запрос на вытягивание.

Рекомендации по запросу на вытягивание

Эти рекомендации основаны на технических методиках работы Google.

Запросы на вытягивание должны быть небольшими

Чем они меньше, тем быстрее и тщательнее удастся их проверить, тем ниже вероятность появления новых ошибок, тем проще откатить изменения и выполнить слияние.

Запрос на вытягивание должен быть настолько малым, чтобы на его проверку инженеру потребовалось не более 30 минут. Старайтесь вносить минимальные изменения только по одному аспекту. Если вам нужно создать крупный запрос на вытягивание, разделите его на несколько более мелких, которые будут размещены в локальной ветви или ветви компонентов MRTK. Старайтесь не добавлять новые ресурсы (например, FBX- или OBJ-файлы) и при возможности используйте уже существующие ресурсы.

Тесты следует добавлять в тот же запрос на вытягивание, в котором размещено исправление или функция (за исключением экстренных ситуаций)

Тесты — это лучший способ гарантировать, что изменения не ухудшат уже существующий код. К сожалению, при отправке запросов на вытягивание о тестах легко забыть. Поэтому требование включать тесты в тот же запрос на вытягивание позволяет гарантировать, что эти тесты будут написаны.

Все новые возможности и исправления ошибок должны сопровождаться соответствующими тестами. Если у вас нет опыта или времени писать тест, создайте запрос на создание тестов и пометьте его меткой Consider for Current Iteration (Учесть в текущей итерации).

Документация должна добавляться в тот же запрос на вытягивание, где размещается само исправление или функция

Большинство разработчиков сначала изучают документацию, а не код, чтобы разобраться в использовании функции. Поддержание актуальности документации значительно упрощает использование MRTK и доверие к этому решению. Документация всегда должна включаться в тот запрос, к которому она относится, что позволяет обеспечить актуальность и согласованность всех элементов.

Убедитесь, что все открытые поля, методы и свойства сопровождаются краткими комментариями с тремя косыми чертами, чтобы наш сайт docfx автоматически создавал описания полей и методов. При необходимости обновите файлы с разметкой Markdown в папке документации.

Описания запросов на вытягивание должны четко и полно описывать изменения

Четкие и полные описания запросов на вытягивание гарантируют, что проверяющие правильно разберутся в их содержимом.

Если вы добавляете компоненты, имеющие отношение к взаимодействию с пользователем, добавьте изображение или видео (в формате GIF) изменяемого компонента. Здесь есть хороший пример. Также можно включить GIF-файлы с состояниями "до" и "после", как, например, в этом запросе на вытягивание. Для создания GIF-файлов из записанных с экрана изображений и видео мы рекомендуем использовать средство ScreenToGif.