Ulepszanie opisów żądań ściągnięcia przy użyciu szablonów

Azure DevOps Services | Azure DevOps Server 2022 r. — Azure DevOps Server 2019 r.

Pisanie dobrych opisów żądań ściągnięcia to doskonały sposób, aby pomóc recenzentom wiedzieć, czego można oczekiwać podczas przeglądania kodu. Są one również doskonałym sposobem na śledzenie elementów, które należy wykonać dla każdej zmiany, takiej jak testowanie, dodawanie testów jednostkowych i aktualizowanie dokumentacji. Szablony żądań ściągnięcia mogą pomóc deweloperom tworzyć doskonałe opisy żądań ściągnięcia spełniające standardy organizacji.

W tym artykule pokazano, jak rozpocząć pracę z szablonami żądań ściągnięcia.

Uwaga

Szablony żądań ściągnięcia mogą zawierać wskazówki, ale są tylko porady. Zasady gałęzi umożliwiają wymuszanie najlepszych rozwiązań, takich jak wymaganie żądań ściągnięcia dla kluczowych gałęzi, takich jak główne, wymaganie pomyślnej kompilacji i wymuszanie wymaganych recenzentów. Aby uzyskać więcej informacji, zobacz zasady gałęzi.

Co to jest szablon żądania ściągnięcia?

Szablon żądania ściągnięcia to plik zawierający tekst języka Markdown , który jest dodawany do opisu żądania ściągnięcia po utworzeniu żądania ściągnięcia.

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 umożliwia utworzenie następującego typu szablonów żądań ściągnięcia:

• Domyślny szablon żądania ściągnięcia, który jest automatycznie stosowany dla wszystkich nowych żądań ściągnięcia w repozytorium, chyba że zostanie zastąpiony przez szablon żądania ściągnięcia specyficznego dla gałęzi
• Szablony żądań ściągnięcia specyficzne dla gałęzi, które są automatycznie stosowane do żądań ściągnięcia przeznaczonych dla określonej gałęzi
• Dodatkowe szablony żądań ściągnięcia, które można opcjonalnie dodać przez twórcę żądania ściągnięcia

Typ szablonu żądania ściągnięcia jest określany przez jego nazwę pliku i lokalizację folderu, zgodnie z opisem w poniższych sekcjach. Nazwy plików i lokalizacje folderów nie są uwzględniane wielkości liter, ale muszą znajdować się w domyślnej gałęzi repozytorium.

Uwaga

Wszystkie pliki szablonów żądania ściągnięcia muszą znajdować się w gałęzi domyślnej (zazwyczaj głównej) repozytorium. Używane są tylko pliki szablonów żądania ściągnięcia z gałęzi domyślnej.

Domyślne szablony żądań ściągnięcia

Domyślne szablony żądań ściągnięcia są automatycznie stosowane do pola opisu po utworzeniu nowego żądania ściągnięcia. Aby skonfigurować repozytorium przy użyciu domyślnego szablonu żądania ściągnięcia, utwórz plik o nazwie pull_request_template.md lub pull_request_template.txt zapisz go w domyślnej gałęzi repozytorium w jednym z następujących folderów.

• Folder o nazwie .azuredevops znajdujący się w folderze głównym repozytorium
• Folder o nazwie .vsts znajdujący się w folderze głównym repozytorium
• Folder o nazwie docs znajdujący się w folderze głównym repozytorium
• Folder główny repozytorium

Dostępnych jest wiele lokalizacji, które zapewniają elastyczność przechowywania szablonów żądań ściągnięcia. Po utworzeniu żądania ściągnięcia Azure Repos przeszukuje wyznaczone foldery w podanej kolejności i używa pierwszego domyślnego szablonu żądania ściągnięcia, który znajdzie.

Po utworzeniu nowego żądania ściągnięcia w repozytorium, chyba że zostanie zastosowany szablon żądania ściągnięcia specyficznego dla gałęzi, zawartość domyślnego szablonu żądania ściągnięcia jest używana do wstępnego wypełniania pola opisu w żądaniu ściągnięcia.

W razie potrzeby możesz edytować lub dodawać do tego opisu i dołączać dodatkowe szablony żądań ściągnięcia , wybierając je z listy rozwijanej Dodaj szablon .

Uwaga

Gdy domyślny lub specyficzny dla gałęzi szablon żądania ściągnięcia jest automatycznie stosowany, zastępuje standardowe komunikaty zatwierdzenia, które są zwykle używane dla domyślnego opisu. Możesz je dodać ponownie, wybierając pozycję Dodaj komunikaty zatwierdzenia.

Szablony żądań ściągnięcia specyficzne dla gałęzi

Szablony żądań ściągnięcia specyficzne dla gałęzi można skonfigurować pod kątem żądań ściągnięcia przeznaczonych dla określonej gałęzi. Aby skonfigurować repozytorium przy użyciu szablonu żądania ściągnięcia specyficznego dla gałęzi, utwórz .txt plik lub .md o nazwie po gałęzi. Nazwa musi być zgodna z pierwszym poziomem nazwy gałęzi, na przykład main, , devreleaselub feature. Każdy szablon żądania ściągnięcia specyficzny dla gałęzi jest stosowany za każdym razem, gdy żądanie ściągnięcia dotyczy tej gałęzi lub dowolnych gałęzi zawartych w nim. Na przykład szablon żądania ściągnięcia o nazwie feature.md zostanie zastosowany, jeśli żądanie ściągnięcia dotyczy feature gałęzi lub dowolnych feature/* gałęzi.

Szablony żądań ściągnięcia specyficzne dla gałęzi muszą być zapisywane w domyślnej gałęzi repozytorium przy użyciu następującej hierarchii folderów: pull_request_template/branches/. Te foldery muszą być oparte na jednym z następujących folderów w repozytorium.

• Folder o nazwie .azuredevops znajdujący się w folderze głównym repozytorium
• Folder o nazwie .vsts znajdujący się w folderze głównym repozytorium
• Folder o nazwie docs znajdujący się w folderze głównym repozytorium
• Folder główny repozytorium

Na przykład szablon żądania ściągnięcia specyficzny dla gałęzi, który powinien być stosowany do wszystkich żądań ściągnięcia do dev gałęzi, zostanie nazwany dev.md lub dev.txt znajdujący się w jednej z następujących lokalizacji.

• <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/

Podobnie jak domyślne szablony żądań ściągnięcia, dostępnych jest wiele lokalizacji, które zapewniają elastyczność przechowywania szablonów żądań ściągnięcia specyficznych dla gałęzi. Po utworzeniu żądania ściągnięcia Azure Repos przeszukuje wyznaczone foldery w kolejności podanej dla szablonu żądania ściągnięcia specyficznego dla gałęzi i użyje pierwszego znalezionego, który pasuje do nazwy gałęzi. Jeśli nie znaleziono szablonu żądania ściągnięcia specyficznego dla gałęzi, Azure Repos następnie wyszukuje domyślny szablon żądania ściągnięcia zgodnie z opisem w poprzedniej sekcji Domyślne szablony żądań ściągnięcia.

Dodatkowe szablony żądań ściągnięcia

Oprócz domyślnych i specyficznych dla gałęzi szablonów żądań ściągnięcia można skonfigurować dodatkowe szablony żądań ściągnięcia. Mogą to być .md pliki lub .txt znajdujące się w jednym z następujących folderów w gałęzi domyślnej.

• <repository root>/.azuredevops/pull_request_template/
• <repository root>/.vsts/pull_request_template/
• <repository root>/docs/pull_request_template/
• <repository root>/pull_request_template/

Po utworzeniu żądania ściągnięcia można dołączyć dowolny z dostępnych szablonów żądań ściągnięcia, wybierając je z listy rozwijanej Dodawanie szablonu . Nazwy na liście rozwijanej są oparte na nazwach plików szablonów.

W poniższym przykładzie wymieniono trzy szablony.

• dev.md — Jest to szablon specyficzny dla gałęzi, który został domyślnie zastosowany do tego żądania ściągnięcia do gałęzi dewelopera, zgodnie z domyślnym komunikatem wymienionym po nazwie pliku.
• additional.md — Jest to dodatkowy szablon.
• pull_request_template.md — Jest to zwykle szablon domyślny, ale został on zastąpiony przez dev.md określony szablon gałęzi w tym żądaniu ściągnięcia. Mimo że nie został on dodany domyślnie, nadal można go zastosować, wybierając go z listy.

Wybierz nazwę żądanego dodatkowego szablonu, aby dołączyć jego zawartość do bieżącego opisu żądania ściągnięcia.

Uwaga

Możesz określić szablon żądania ściągnięcia, aby zastąpić dowolne zgodne domyślne lub specyficzne dla gałęzi żądanie ściągnięcia, dołączając ?template=name.md do ciągu zapytania.

Zobacz też

• Tworzenie żądania ściągnięcia w celu przejrzenia i scalenia kodu
• Informacje o gałęziach i zasadach gałęzi