Współtwórz kod TensorFlow

Niezależnie od tego, czy dodajesz funkcję utraty, poprawiasz zasięg testów, czy piszesz dokument RFC dotyczący poważnej zmiany w projekcie, ta część przewodnika dla współautorów pomoże Ci zacząć. Dziękujemy za Twoją pracę i zainteresowanie udoskonalaniem TensorFlow.

Zanim zaczniesz

Zanim przekażesz kod źródłowy do projektu TensorFlow, przejrzyj plik CONTRIBUTING.md w repozytorium GitHub projektu. Na przykład zobacz plik CONTRIBUTING.md w podstawowym repozytorium TensorFlow. Wszyscy współautorzy kodu muszą podpisać umowę licencyjną współautora (CLA).

Aby uniknąć powielania pracy, przed rozpoczęciem pracy nad nietrywialną funkcją przejrzyj aktualne lub proponowane dokumenty RFC i skontaktuj się z programistami na forach TensorFlow ( developers@tensorflow.org ). Podejmujemy dość wybiórczą decyzję o dodaniu nowej funkcjonalności, a najlepszym sposobem na wniesienie wkładu i pomoc w projekcie jest praca nad znanymi problemami.

Problemy dla nowych autorów

Nowi współautorzy powinni szukać następujących tagów, szukając pierwszego wkładu do bazy kodu TensorFlow. Zdecydowanie zalecamy, aby nowi współpracownicy w pierwszej kolejności zajęli się projektami „dobry pierwszy problem” i „przyjmują uwagi z zadowoleniem”; pomaga to współautorowi zapoznać się z przepływem pracy, a głównym programistom zapoznać się z współautorem.

Jeśli jesteś zainteresowany rekrutacją zespołu, który pomoże uporać się z problemem na dużą skalę lub nową funkcją, wyślij e-mail na adres grupy programistów@ i przejrzyj naszą aktualną listę dokumentów RFC.

Przegląd kodu

Nowe funkcje, poprawki błędów i wszelkie inne zmiany w bazie kodu podlegają przeglądowi kodu.

Przeglądanie kodu wniesionego do projektu jako żądania ściągnięcia jest kluczowym elementem rozwoju TensorFlow. Zachęcamy każdego, aby zaczął przeglądać kod przesłany przez innych programistów, zwłaszcza jeśli z danej funkcji prawdopodobnie będziesz korzystać.

Oto kilka pytań, o których warto pamiętać podczas procesu przeglądu kodu:

  • Czy chcemy tego w TensorFlow? Czy jest prawdopodobne, że będzie używany? Czy Tobie, jako użytkownikowi TensorFlow, podoba się zmiana i zamierzasz z niej skorzystać? Czy jest to zmiana w zakresie TensorFlow? Czy koszt utrzymania nowej funkcji będzie wart jej korzyści?
  • Czy kod jest spójny z API TensorFlow? Czy publiczne funkcje, klasy i parametry są dobrze nazwane i intuicyjnie zaprojektowane?

  • Czy obejmuje dokumentację? Czy wszystkie funkcje publiczne, klasy, parametry, typy zwracane i przechowywane atrybuty są nazwane zgodnie z konwencjami TensorFlow i są jasno udokumentowane? Czy nowa funkcjonalność jest opisana w dokumentacji TensorFlow i zilustrowana przykładami, jeśli to możliwe? Czy dokumentacja renderuje się prawidłowo?

  • Czy kod jest czytelny dla człowieka? Czy jest mało redundancji? Czy należy poprawić nazwy zmiennych, aby zapewnić przejrzystość i spójność? Czy należy dodawać komentarze? Czy należy usuwać komentarze jako nieprzydatne lub obce?

  • Czy kod jest wydajny? Czy można go łatwo przepisać, aby działał wydajniej?

  • Czy kod jest wstecznie kompatybilny z poprzednimi wersjami TensorFlow?

  • Czy nowy kod doda nowe zależności od innych bibliotek?

Testuj i poprawiaj zasięg testów

Wysokiej jakości testy jednostkowe są kamieniem węgielnym procesu rozwoju TensorFlow. W tym celu wykorzystujemy obrazy Dockera. Funkcje testowe mają odpowiednią nazwę i odpowiadają za sprawdzanie ważności algorytmów oraz różnych opcji kodu.

Wszystkie nowe funkcje i poprawki błędów muszą obejmować odpowiedni zakres testów. Z radością przyjmujemy także wkład w postaci nowych przypadków testowych lub ulepszeń istniejących testów. Jeśli odkryjesz, że nasze istniejące testy nie zostały ukończone — nawet jeśli nie jest to obecnie przyczyną błędu — zgłoś problem i, jeśli to możliwe, wyślij prośbę o ściągnięcie.

Szczegółowe informacje na temat procedur testowania w każdym projekcie TensorFlow można znaleźć w plikach README.md i CONTRIBUTING.md w repozytorium projektu w serwisie GitHub.

Szczególne obawy związane z odpowiednimi testami :

  • Czy każda funkcja publiczna i każda klasa są testowane?
  • Czy przetestowano rozsądny zestaw parametrów , ich wartości, typów wartości i kombinacji?
  • Czy testy potwierdzają, że kod jest poprawny i robi to, do czego według dokumentacji jest przeznaczony?
  • Jeśli zmiana polega na naprawieniu błędu, czy uwzględniony jest test bez regresji ?
  • Czy testy przechodzą pomyślnie kompilację ciągłej integracji ?
  • Czy testy obejmują każdą linię kodu? Jeśli nie, czy wyjątki są rozsądne i wyraźne?

Jeśli znajdziesz jakieś problemy, rozważ pomoc autorowi w zrozumieniu tych problemów i ich rozwiązaniu.

Popraw komunikaty o błędach lub dzienniki

Mile widziane są wkłady poprawiające komunikaty o błędach i rejestrowanie.

Przepływ pracy w ramach wkładu

Wkład w kod — poprawki błędów, nowy rozwój, udoskonalanie testów — odbywa się zgodnie z przepływem pracy skupionym na GitHub. Aby wziąć udział w rozwoju TensorFlow, załóż konto GitHub. Następnie:

  1. Utwórz rozwidlenie repozytorium, nad którym planujesz pracować. Przejdź do strony repozytorium projektu i użyj przycisku Fork . Spowoduje to utworzenie kopii repozytorium pod Twoją nazwą użytkownika. (Więcej informacji na temat rozwidlenia repozytorium można znaleźć w tym przewodniku .)

  2. Sklonuj repozytorium do systemu lokalnego.

    $ git clone git@github.com:your-user-name/project-name.git

  3. Utwórz nową gałąź, w której będziesz przechowywać swoją pracę.

    $ git checkout -b new-branch-name

  4. Pracuj nad nowym kodem. Pisz i uruchamiaj testy.

  5. Zatwierdź zmiany.

    $ git add -A

    $ git commit -m "commit message here"

  6. Przepchnij zmiany do repozytorium GitHub.

    $ git push origin branch-name

  7. Otwórz żądanie ściągnięcia (PR). Przejdź do oryginalnego repozytorium projektu w serwisie GitHub. Pojawi się komunikat dotyczący ostatnio wypchniętej gałęzi z pytaniem, czy chcesz otworzyć żądanie ściągnięcia. Postępuj zgodnie z instrukcjami, porównaj repozytoria i prześlij żądanie ściągnięcia. Spowoduje to wysłanie wiadomości e-mail do osób zatwierdzających. Możesz rozważyć wysłanie wiadomości e-mail na listę mailingową, aby uzyskać większą widoczność. (Aby uzyskać więcej informacji, zobacz przewodnik GitHub dotyczący PR .

  8. Opiekunowie i inni współpracownicy sprawdzą Twój PR . Weź udział w rozmowie i spróbuj wprowadzić żądane zmiany . Po zatwierdzeniu żądania PR kod zostanie scalony.

Zanim zaczniesz pracować nad kolejnym wpisem , upewnij się, że Twoje lokalne repozytorium jest aktualne.

  1. Ustaw pilota nadrzędnego. (Musisz to zrobić tylko raz na projekt, a nie za każdym razem.)

    $ git remote add upstream git@github.com:tensorflow/project-repo-name

  2. Przejdź do lokalnej gałęzi głównej.

    $ git checkout master

  3. Wyciągnij zmiany z poprzedniego źródła.

    $ git pull upstream master

  4. Przepchnij zmiany na swoje konto GitHub. (Opcjonalne, ale dobra praktyka.)

    $ git push origin master

  5. Utwórz nowy oddział, jeśli rozpoczynasz nową pracę.

    $ git checkout -b branch-name

Dodatkowe zasoby git i GitHub:

Lista kontrolna współautora