Улучшайте описания запросов на вытягивание с помощью шаблонов
Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019
Написание хороших описаний pull request — отличный способ помочь рецензентам понять, чего ожидать при ревизии кода. Они также отличный способ помочь отслеживать вещи, которые должны быть выполнены для каждого изменения, таких как тестирование, добавление модульных тестов и обновление документации. Шаблоны пул-реквестов позволяют разработчикам создавать качественные описания, соответствующие стандартам вашей организации.
В этой статье показано, как начать использовать шаблоны pull-запросов.
Примечание.
Шаблоны пулл-реквестов могут давать советы, но они только для информации. Используйте политики ветвей, чтобы применять лучшие практики, такие как необходимость запросов на pull requests для ключевых ветвей, таких как main, требование успешной сборки и обязательное участие необходимых рецензентов. Дополнительную информацию см. в политиках ветки .
Предпосылки
| Категория | Требования |
|---|---|
| доступ к проекту | Член проекта . |
| Разрешения | — Просмотр кода в частных проектах: по крайней мере базовый доступ. — Клонирование или внесение вклада в код в частных проектах: Участник группы безопасности для участников или наличие соответствующих разрешений в проекте. — Задайте разрешения ветви или репозитория: управление разрешениями для ветви или репозитория. — Измените ветвь по умолчанию: . Измените политики и разрешения для репозитория. — Импорт репозитория: член группы безопасности администраторов проекта или разрешение уровня проекта Git на создание репозитория установлено в «Разрешить» . Дополнительные сведения см. в разделе "Настройка разрешений репозитория Git". |
| услуги | Repos включено. |
| Инструменты | Необязательно. Используйте команды az repos: Azure DevOps CLI. |
Примечание.
В общедоступных проектах пользователи с доступом Stakeholder имеют полный доступ к Azure Repos, включая возможность просмотра, клонирования и участия в коде.
| Категория | Требования |
|---|---|
| доступ к проекту | Член проекта . |
| Разрешения | — Просмотр кода: доступ уровня Basic хотя бы . — Клонирование или участие в коде: член группы безопасности участников или обладатель соответствующих разрешений в проекте. |
| услуги | Repos включено. |
Что такое шаблон пулл-реквеста?
Шаблон запроса на вытягивание — это файл, содержащий текст Markdown, который добавляется в описание запроса на вытягивание при создании запроса на вытягивание.
Thank you for your contribution to the Fabrikam Fiber repo.
Before submitting this PR, please make sure:
- [ ] Your code builds clean without any errors or warnings
- [ ] You are using approved terminology
- [ ] You have added unit tests
Azure Repos позволяет создавать следующие шаблоны пулл-реквестов:
- Шаблон запроса на вытягивание по умолчанию , который автоматически применяется ко всем новым запросам на вытягивание в репозитории, если не заменяется на шаблон запроса, специфичный для ветви.
- Шаблоны запросов на вытягивание, для конкретной ветки, которые автоматически применяются к таким запросам
- дополнительные шаблоны запросов на вытягивание, которые могут быть дополнительно добавлены создателем запроса на вытягивание
Тип шаблона pull request определяется именем файла и расположением папки, как описано в следующих разделах. Имена файлов и расположения папок не учитывает регистр, но они должны находиться в ветви репозитория по умолчанию.
Примечание.
Все файлы шаблона pull request должны находиться в ветви по умолчанию (как правило, основной) репозитория. Используются только файлы шаблонов для запросов на внесение изменений из ветви по умолчанию.
Шаблоны pull-запросов по умолчанию
Шаблоны pull request по умолчанию автоматически применяются к полю описания при создании нового pull request. Чтобы настроить репозиторий с пулл-реквест-шаблоном по умолчанию, создайте файл с именем pull_request_template.md или pull_request_template.txt и сохраните его в основной ветке репозитория в одной из следующих папок.
- Папка с именем
.azuredevops, содержащаяся в корневой папке репозитория - Папка с именем
.vsts, содержащаяся в корневой папке репозитория - Папка с именем
docs, содержащаяся в корневой папке репозитория - Корневая папка репозитория
Предоставляются различные места, чтобы дать вам гибкость в том, где вы храните шаблоны pull request. При создании запроса на вытягивание Azure Repos выполняет поиск указанных папок в указанном порядке и использует первый шаблон запроса на вытягивание по умолчанию, который он находит.
При создании запроса на вытягивание в репозитории, если не применяется специфический шаблон запроса на вытягивание для ветки , используется содержимое шаблона запроса на вытягивание по умолчанию для предварительного заполнения поля описания.
Вы можете изменить или добавить в это описание и добавить дополнительные шаблоны запросов на вытягивание, выбрав их из раскрывающегося списка Добавить шаблон.
Примечание.
Когда шаблон пулреквеста по умолчанию или для конкретной ветви применяется автоматически, он заменяет стандартные сообщения фиксации, которые обычно используются для стандартного описания. Их можно добавить обратно, выбрав Добавить сообщения коммитов.
Шаблоны pull-реквестов для конкретной ветви
Шаблоны запросов на вытягивание конкретной ветви можно настроить для запросов на вытягивание, предназначенных для конкретной ветви. Чтобы настроить репозиторий с шаблоном запроса на вытягивание для конкретной ветки, создайте файл .txt или .md, назвав его в соответствии с вашей веткой. Имя должно соответствовать первому уровню имени ветви, например main, dev, releaseили feature. Шаблон запроса на вытягивание для соответствующей ветви применяется в случае, если запрос на вытягивание предназначен для этой ветви или любых ветвей, содержащихся под ней. Например, шаблон запроса на вытягивание с именем feature.md будет применен, если запрос на вытягивание предназначен для ветви feature или любой ветви feature/*.
Шаблоны запросов на вытягивание, специфичные для ветвей, должны сохраняться в основной ветви вашего репозитория с использованием следующей иерархии папок: pull_request_template/branches/. Эти папки должны быть основаны на одной из следующих папок в репозитории.
- Папка с именем
.azuredevops, содержащаяся в корневой папке репозитория - Папка с именем
.vsts, содержащаяся в корневой папке репозитория - Папка с именем
docs, содержащаяся в корневой папке репозитория - Корневая папка репозитория
Например, шаблон запроса на вытягивание, который должен применяться ко всем запросам на вытягивание в ветвь dev, будет называться dev.md или dev.txt и находиться в одном из следующих расположений.
<repository root>/.azuredevops/pull_request_template/branches/<repository root>/.vsts/pull_request_template/branches/<repository root>/docs/pull_request_template/branches/<repository root>/pull_request_template/branches/
Как и шаблоны запросов на вытягивание по умолчанию, предоставляется несколько мест расположения, чтобы обеспечить гибкость в хранении специфичных для веток шаблонов запросов на вытягивание. При создании запроса на вытягивание Azure Repos выполняет поиск указанных папок в заданном порядке для шаблона запроса на вытягивание, специфичного для ветки, и использует первый найденный, который соответствует имени ветки. Если не найден специфичный для ветви шаблон запроса на вытягивание, Azure Repos затем осуществляет поиск шаблона запроса по умолчанию, как описано в предыдущем разделе «Шаблоны запросов на вытягивание по умолчанию».
Дополнительные шаблоны для запросов «pull request»
Помимо шаблонов запросов на вытягивание по умолчанию и шаблонов для отдельных ветвей, можно настроить дополнительные шаблоны запросов на вытягивание. Они могут быть файлами .md или .txt, расположенными в одной из следующих папок в основной ветке по умолчанию.
<repository root>/.azuredevops/pull_request_template/<repository root>/.vsts/pull_request_template/<repository root>/docs/pull_request_template/<repository root>/pull_request_template/
При создании запроса на вытягивание можно добавить любой из доступных шаблонов запросов на вытягивание, выбрав их из раскрывающегося списка Добавить шаблон. Имена в раскрывающемся списке основаны на именах файлов шаблонов.
В следующем примере перечислены три шаблона.
-
dev.md. Это шаблон, который был применен по умолчанию к этому pull request в ветвь разработки, о чем говорится в стандартном сообщении , указанном после имени файла. -
additional.md— это дополнительный шаблон. -
pull_request_template.md— Обычно это шаблон по умолчанию, но он был переопределен шаблоном, специфичным для веткиdev.md, в этом pull request. Несмотря на то, что он не был добавлен по умолчанию, его можно применить, выбрав его из списка.
Выберите имя требуемого дополнительного шаблона, чтобы добавить его содержимое в текущее описание запроса на вытягивание.
Примечание.
Вы можете указать шаблон запроса на вытягивание, чтобы заменить любой подходящий запрос по умолчанию или запрос для конкретной ветки, добавив ?template=name.md в строку запроса.