Żądania ściągnięcia

Wymagania wstępne

Jeśli wcześniej nie współtwomentowano projektu firmy Microsoft, może zostać poproszony o podpisanie umowy licencyjnej udziału. Komentarz w pnecie ściągnięciem będzie Cię o tym wiedzieć, jeśli to zrobisz.

Ważne

Jeśli jesteś pracownikiem firmy Microsoft i nie jesteś członkiem organizacji firmy Microsoft na platformie GitHub,przed rozpoczęciem żądania ściągnięć połącz swoje konta Microsoft i GitHub w sieci firmowej, odwiedzając stronę Open Source at Microsoft (Oprogramowanie open source w firmie Microsoft). Istnieje kilka procesów, które należy wykonać z wyprzedzeniem.

Tworzenie żądania ściągnięcia

Gdy wszystko będzie gotowe do przesyłania żądania ściągnnięcia, utwórz żądanie ściągnięć przeznaczone dla gałęzi main. Aby uzyskać poprawki błędów w okresie ustabilizowania wydania, poszukaj najnowszej prerelease/* gałęzi. Nowe funkcje powinny zawsze trafiać do . main

Zapoznaj się z wytycznymi i upewnij się, że żądanie ściągnięcie jest zgodne z wytycznymi.

  • Pamiętaj, aby odwołać się do dowolnego problemu/żądania funkcji lub zadania, którego dotyczy żądanie ściągnięcie.
  • Sprawdź, czy żądanie ściągnięcie zawiera tylko pliki/zmiany związane z żądaniem ściągnnięcia.
  • Sprawdź, czy dokumentacja jest aktualny i dołączona. Sprawdź, czy wszystkie pola publiczne mają komentarze.
  • W przypadku dodawania nowej funkcji sprawdź, czy testy zostały uwzględnione w celu zweryfikowania tej funkcji (zobacz UnitTests).
  • Jeśli naprawisz usterkę, napisz test, aby zweryfikować poprawkę usterki.

Konserwatorzy projektu przejrzycie wprowadzone zmiany. Chcemy przejrzeć wszystkie zmiany w ciągu trzech dni roboczych. Zaadresuj wszelkie komentarze do recenzji, wypchń do gałęzi tematu i opublikuj komentarz z informacjami o nowościach do przejrzenia.

Uwaga

Wszystkie przesłane do projektu ściągnięcie zostanie również zweryfikowane zgodnie z przewodnikiem po standardach kodowania MRTK,dlatego należy je przejrzeć przed przesłaniem swojego wniosku o ściągnięcie, aby zapewnić sprawny proces.

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

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

Zachowaj małe żądania ściągnięć

Mniejsze błędy są przeglądane szybciej i dokładniej, są mniej prawdopodobne do wprowadzenia usterek, łatwiejsze do wycofania i łatwiejsze do scalenia.

Żądania ściągnięć powinny być na tyle małe, aby inżynier mógł je przejrzeć w ciągu 30 minut. Spróbuj wprowadzić minimalną zmianę, która dotyczy tylko jednej rzeczy. Jeśli musisz utworzyć duże ściągnięcie ściągnięcie, podziel je na kilka ściągnięć ściągnięć, które są dzielone na gałąź lokalną lub gałąź funkcji zestawu mrtk. Unikaj dodawania nowych zasobów (np. plików fbx, obj) i zamiast tego staraj się ponownie używać istniejących zasobów.

Testy powinny być dodawane w tym samym próceniu ściągnięciem co poprawka/funkcja, z wyjątkiem sytuacji awaryjnych

Testy to najlepszy sposób na zapewnienie, że zmiany nie zawrócą istniejącego kodu, ale można również łatwo zapomnieć o testach podczas przesyłania żądań ściągnięć. Wymaganie od nich współpracy z Żądaniem ściągnięcie jest doskonałym sposobem na zapewnienie, że testy zostaną napisane.

Z każdą funkcją i poprawną usterką powinny być skojarzone testy. Jeśli nie masz doświadczenia ani czasu na napisanie testu, utwórz problem podczas pisania testów i oznacz je etykietą Rozważ dla bieżącej iteracji.

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

Większość deweloperów najpierw przyjrzy się dokumentacji, a nie kodowi, gdy rozumie, jak używać funkcji. Zapewnienie, że dokumentacja jest aktualne, znacznie ułatwia ludziom korzystanie z mrTK i korzystanie z niego. Dokumentacja powinna być zawsze powiązana z powiązanym ściągnięciem, aby zapewnić, że elementy pozostaną aktualne i spójne.

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

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

Jasne i pełne opisy żądań ściągnięć zapewniają, że recenzentzy rozumieją, co przeglądają.

W przypadku dodawania funkcji, które zawierają interfejs użytkownika, dodaj obraz/plik gif funkcji, która jest zmieniana. Oto dobry przykład. Inną sugestią jest mieć plik gif o formacie Before i After, na przykład w tym żądaniu ściągnięcie. Narzędzie, które jest zalecane do generowania plików GIF z przechwytywania ekranu, to ScreenToGif.