Proces TensorFlow RFC

Każda nowa funkcja TensorFlow zaczyna życie jako żądanie komentarza (RFC).

RFC to dokument opisujący wymagania i proponowane zmiany, które je rozwiążą. W szczególności dokument RFC:

  • Być sformatowany zgodnie z szablonem RFC .
  • Należy przesłać jako żądanie ściągnięcia do katalogu Community/rfcs .
  • Przed akceptacją należy poddać się dyskusji i spotkaniu przeglądowemu.

Celem prośby o komentarz TensorFlow (RFC) jest zaangażowanie społeczności TensorFlow w rozwój, poprzez uzyskanie opinii od interesariuszy i ekspertów oraz szerokie komunikowanie zmian projektowych.

Jak przesłać dokument RFC

  1. Przed przesłaniem RFC przedyskutuj swoje cele ze współpracownikami i opiekunami projektu, aby uzyskać wczesną informację zwrotną. Skorzystaj z listy mailingowej programistów dla danego projektu (developers@tensorflow.org lub listy dla odpowiedniego SIG).

  2. Przygotuj wersję roboczą RFC.

    • Przeczytaj kryteria przeglądu projektu
    • Postępuj zgodnie z szablonem RFC .
    • Nazwij swój plik RFC YYYYMMDD-descriptive-name.md , gdzie YYYYMMDD to data przesłania, a descriptive-name odnosi się do tytułu Twojego RFC. (Na przykład, jeśli dokument RFC nosi tytuł Parallel Widgets API , możesz użyć nazwy pliku 20180531-parallel-widgets.md .
    • Jeśli masz obrazy lub inne pliki pomocnicze, utwórz katalog w postaci YYYYMMDD-descriptive-name w którym będziesz przechowywać te pliki.

    Po napisaniu wersji roboczej RFC, przed jej przesłaniem uzyskaj opinie od opiekunów i współpracowników.

    Napisanie kodu implementacyjnego nie jest wymogiem, ale może pomóc w zaprojektowaniu dyskusji.

  3. Zrekrutuj sponsora.

    • Sponsor musi być opiekunem projektu.
    • Zidentyfikuj sponsora w dokumencie RFC przed opublikowaniem żądania PR.

    Możesz opublikować RFC bez sponsora, ale jeśli w ciągu miesiąca od opublikowania PR nadal nie będzie sponsora, zostanie ono zamknięte.

  4. Prześlij swój dokument RFC jako żądanie ściągnięcia do tensorflow/community/rfcs .

    Dołącz tabelę nagłówków i zawartość sekcji Cel do komentarza do żądania ściągnięcia, korzystając z narzędzia Markdown. Aby zapoznać się z przykładem, zobacz ten przykładowy dokument RFC . Dołącz uchwyty GitHub współautorów, recenzentów i sponsorów.

    Na górze PR określ, jak długi będzie okres komentowania. Powinno to upłynąć co najmniej dwa tygodnie od opublikowania PR.

  5. Wyślij e-mail do listy mailingowej programistów z krótkim opisem, linkiem do PR i prośbą o sprawdzenie. Postępuj zgodnie z formatem poprzednich wysyłek, jak widać w tym przykładzie .

  6. Sponsor poprosi o spotkanie komisji ds. przeglądu nie wcześniej niż dwa tygodnie po opublikowaniu PR RFC. Jeśli dyskusja jest ożywiona, poczekaj, aż się rozstrzygnie, zanim przejdziesz do recenzji. Celem spotkania przeglądowego jest rozwiązanie drobnych problemów; należy wcześniej osiągnąć konsensus w głównych kwestiach.

  7. Spotkanie może zatwierdzić dokument RFC, odrzucić go lub zażądać zmian, zanim będzie można go ponownie rozpatrzyć. Zatwierdzone dokumenty RFC zostaną połączone w społeczność/rfcs , a odrzucone dokumenty RFC zostaną zamknięte.

Uczestnicy RFC

W proces RFC zaangażowanych jest wiele osób:

  • Autor RFC — jeden lub więcej członków społeczności, którzy piszą dokument RFC i zobowiązują się do jego wspierania w trakcie całego procesu

  • Sponsor RFC — opiekun, który sponsoruje RFC i poprowadzi go przez proces przeglądu RFC

  • komisja przeglądowa — grupa opiekunów, których zadaniem jest rekomendowanie przyjęcia RFC

  • Każdy członek społeczności może pomóc, przekazując opinię na temat tego, czy dokument RFC spełni jego potrzeby.

Sponsorzy RFC

Sponsor to osoba utrzymująca projekt odpowiedzialna za zapewnienie możliwie najlepszego wyniku procesu RFC. To zawiera:

  • Opowiadanie się za proponowanym projektem.
  • Kierowanie dokumentem RFC w celu dostosowania się do istniejących konwencji dotyczących projektowania i stylu.
  • Kierowanie komisją przeglądową w celu osiągnięcia produktywnego konsensusu.
  • Jeżeli komisja rewizyjna zażąda zmian, upewnij się, że zostały one wprowadzone, a następnie uzyskaj zgodę członków komisji.
  • Jeśli dokument RFC przejdzie do wdrożenia:
    • Zapewnienie zgodności proponowanej realizacji z projektem.
    • Koordynuj działania z odpowiednimi stronami, aby pomyślnie wdrożyć wdrożenie.

Komitety recenzujące RFC

Komisja rewizyjna decyduje na zasadzie konsensusu, czy zatwierdzić, odrzucić lub zażądać zmian. Są odpowiedzialni za:

  • Zapewnienie uwzględnienia istotnych elementów opinii publicznej.
  • Dodawanie notatek ze spotkań jako komentarzy do żądania ściągnięcia.
  • Podanie powodów swoich decyzji.

Skład komisji rewizyjnej może ulec zmianie w zależności od konkretnego stylu zarządzania i przywództwa każdego projektu. W przypadku podstawowego TensorFlow komisja będzie składać się z autorów projektu TensorFlow, którzy posiadają wiedzę fachową w danym obszarze domeny.

Członkowie społeczności i proces RFC

Celem dokumentów RFC jest zapewnienie, że społeczność będzie dobrze reprezentowana i obsługiwana przez nowe zmiany w TensorFlow. Członkowie społeczności mają obowiązek uczestniczyć w przeglądaniu dokumentów RFC, jeśli są zainteresowani wynikiem.

Członkowie społeczności zainteresowani dokumentem RFC powinni:

  • Przekazuj informację zwrotną tak szybko, jak to możliwe, aby zapewnić odpowiednią ilość czasu na przemyślenie.
  • Zanim przekażesz opinię, przeczytaj dokładnie dokumenty RFC .
  • Bądź obywatelski i konstruktywny .

Wdrażanie nowych funkcji

Po zatwierdzeniu dokumentu RFC można rozpocząć wdrażanie.

Jeśli pracujesz nad nowym kodem implementującym RFC:

  • Upewnij się, że rozumiesz funkcję i projekt zatwierdzony w dokumencie RFC. Zadawaj pytania i omawiaj podejście przed rozpoczęciem pracy.
  • Nowe funkcje muszą obejmować nowe testy jednostkowe, które sprawdzają, czy funkcja działa zgodnie z oczekiwaniami. Dobrym pomysłem jest napisanie tych testów przed napisaniem kodu.
  • Postępuj zgodnie z Przewodnikiem po stylu kodu TensorFlow
  • Dodaj lub zaktualizuj odpowiednią dokumentację API. Odwołaj się do RFC w nowej dokumentacji.
  • Postępuj zgodnie z innymi wytycznymi zawartymi w pliku CONTRIBUTING.md w repozytorium projektu, do którego bierzesz udział.
  • Uruchom testy jednostkowe przed przesłaniem kodu.
  • Współpracuj ze sponsorem RFC, aby pomyślnie wylądować nowy kod.

Utrzymywanie wysokiej poprzeczki

Chociaż zachęcamy i doceniamy każdego współautora, poprzeczka akceptacji RFC jest celowo utrzymywana wysoko. Nowa funkcja może zostać odrzucona lub wymagać znaczących zmian na dowolnym z poniższych etapów:

  • Wstępne rozmowy projektowe na odpowiedniej liście mailingowej.
  • Nie udało się pozyskać sponsora.
  • Krytyczne zastrzeżenia na etapie informacji zwrotnej.
  • Brak osiągnięcia konsensusu podczas przeglądu projektu.
  • Wątpliwości zgłaszane podczas wdrażania (na przykład: niemożność osiągnięcia kompatybilności wstecznej, obawy dotyczące konserwacji).

Jeśli proces ten działa dobrze, oczekuje się, że specyfikacje RFC zawiodą raczej na wcześniejszych, a nie późniejszych etapach. Zatwierdzony dokument RFC nie gwarantuje zobowiązania do wdrożenia, a akceptacja proponowanej implementacji RFC nadal podlega zwykłemu procesowi przeglądu kodu.

Jeśli masz jakiekolwiek pytania dotyczące tego procesu, możesz zadać je na liście mailingowej programistów lub zgłosić problem w tensorflow/community .