Żądania ściągnięcia — MRTK2

Wymagania wstępne

Jeśli wcześniej nie współtworzeno projektu firmy Microsoft, może zostać wyświetlony monit o podpisanie umowy licencyjnej udziału. Komentarz w żądaniu ściągnięcia poinformuje Cię, jeśli to zrobisz.

Ważne

Jeśli jesteś pracownikiem firmy Microsoft i nie jesteś członkiem organizacji firmy Microsoft w usłudze GitHub, przed rozpoczęciem żądania ściągnięcia połącz swoje konta Microsoft i GitHub w sieci corpnet, odwiedzając witrynę Open Source w firmie Microsoft . Istnieją pewne rzeczy procesu, które należy wykonać z wyprzedzeniem.

Tworzenie żądania ściągnięcia

Gdy wszystko będzie gotowe do przesłania żądania ściągnięcia, utwórz żądanie ściągnięciaprzeznaczone dla głównej gałęzi. W przypadku poprawek błędów w okresie stabilizacji wydania poszukaj najnowszej prerelease/* gałęzi. Nowe funkcje powinny zawsze przechodzić do elementu main.

Zapoznaj się z wytycznymi i upewnij się, że żądanie ściągnięcia spełnia wytyczne.

• Pamiętaj, aby odwołać się do dowolnego żądania dotyczącego problemu/funkcji lub zadania, z którego odnosi się żądanie ściągnięcia.
• Sprawdź, czy żądanie ściągnięcia zawiera tylko pliki/zmiany związane z żądaniem ściągnięcia.
• Sprawdź, czy dokumentacja jest aktualna i dołączona. Sprawdź, czy wszystkie pola publiczne mają komentarze.
• W przypadku dodawania nowej funkcji sprawdź, czy testy są uwzględniane w celu zweryfikowania funkcji (zobacz UnitTests).
• Jeśli usunięto usterkę, napisz test w celu zweryfikowania poprawki usterki.

Osoby odpowiedzialne za projekt przejrzy zmiany. Chcemy przejrzeć wszystkie zmiany w ciągu trzech dni roboczych. Zaasuj wszelkie komentarze do przeglądu, wypchnij do gałęzi tematu i opublikuj komentarz informujący nas, że są nowe rzeczy do przejrzenia.

Uwaga

Wszystkie żądania ściągnięcia przesłane do projektu również zostaną zweryfikowane zgodnie z przewodnikiem dotyczącym standardów kodowania zestawu narzędzi MRTK, dlatego przed przesłaniem żądania ściągnięcia należy je przejrzeć, aby zapewnić sprawny proces.

Wskazówki dotyczące żądań ściągnięcia

Te wytyczne są oparte na praktykach inżynieryjnych firmy Google.

Utrzymywanie małych żądań ściągnięcia

Mniejsze żądania ściągnięcia są przeglądane szybciej i dokładnie, są mniej narażone na wprowadzanie usterek, łatwiejsze do wycofywania i łatwiejsze do scalenia.

Żądania ściągnięcia powinny być wystarczająco małe, aby inżynier mógł przejrzeć je w ciągu 30 minut. Spróbuj wprowadzić minimalną zmianę, która dotyczy tylko jednej rzeczy. Jeśli musisz utworzyć duże żądanie ściągnięcia, podzielić je na kilka żądań ściągnięcia, które przechodzą do gałęzi lokalnej lub gałęzi funkcji zestawu narzędzi MRTK. Unikaj dodawania nowych zasobów (np. fbx, plików obj) i zamiast tego należy ponownie używać istniejących zasobów.

Testy należy dodać w tym samym żądaniu ściągnięcia co poprawka/funkcja, z wyjątkiem sytuacji awaryjnych

Testy są najlepszym sposobem zapewnienia, że zmiany nie ustępują istniejącego kodu, ale można również łatwo zapomnieć o testach podczas przesyłania żądań ściągnięcia. Wymaganie, aby przejść z żądaniem ściągnięcia jest doskonałym sposobem na upewnienie się, że testy zostaną napisane.

Każda funkcja i poprawka usterek powinny mieć skojarzone z nią testy. Jeśli nie masz wiedzy lub czasu na napisanie testu, utwórz problem w celu napisania testów i oznacz je etykietą Rozważ dla bieżącej iteracji.

Dokumentacja powinna zostać dodana w tym samym żądaniu ściągnięcia co poprawka/funkcja

Większość deweloperów najpierw zapozna się z dokumentacją, a nie kodem, gdy rozumie sposób korzystania z funkcji. Zapewnienie aktualności dokumentacji znacznie ułatwia użytkownikom korzystanie z zestawu narzędzi MRTK i korzystanie z nich. Zawsze należy powiązać dokumentację z powiązanym ściąganiem, aby zapewnić aktualność i spójność elementów.

Upewnij się, że każde pole publiczne, metoda, właściwość ma komentarze podsumowania potrójnego ukośnika , dzięki czemu nasza witryna docfx może generować opisy pól/metod. W razie potrzeby zaktualizuj pliki markdown w folderze Dokumentacja.

Opisy żądań ściągnięcia powinny jasno i całkowicie opisywać zmiany

Jasne i kompletne opisy żądań ściągnięcia zapewniają recenzentom zrozumienie, co przeglądają.

W przypadku dodawania funkcji zawierających środowiska użytkownika dodaj obraz /gif funkcji, którą zmieniasz. Oto dobry przykład. Inną sugestią jest utworzenie pliku GIF przed i po, na przykład w tym żądaniu ściągnięcia. Zalecamy generowanie gifów z przechwytywania ekranu to ScreenToGif.