Przyczyń się do tworzenia kodu TensorFlow

Niezależnie od tego, czy dodajesz funkcję straty, poprawiasz pokrycie testami, czy piszesz RFC dla poważnej zmiany projektu, ta część przewodnika dla autorów pomoże Ci zacząć. Dziękujemy za pracę i zainteresowanie doskonaleniem TensorFlow.

Zanim zaczniesz

Zanim prześlesz kod źródłowy do projektu TensorFlow, przejrzyj plik CONTRIBUTING.md w repozytorium GitHub projektu. Na przykład zobacz plik CONTRIBUTING.md w głównym repozytorium TensorFlow. Wszyscy współtwórcy kodu są zobowiązani do podpisania umowy licencyjnej współtwórcy (CLA).

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

Problemy dla nowych współtwórców

Nowi kontrybutorzy powinni szukać następujących tagów podczas wyszukiwania pierwszego wkładu do bazy kodu TensorFlow. Zdecydowanie zalecamy, aby nowi kontrybutorzy najpierw zajęli się projektami „dobry pierwszy problem” i „wkłady mile widziane”; pomaga to współtwórcy zapoznać się z przepływem pracy, a głównym programistom zapoznać się z współtwórcą.

Jeśli jesteś zainteresowany rekrutacją zespołu, który pomoże rozwiązać problem na dużą skalę lub nową funkcję, wyślij wiadomość e-mail do grupy developers@ i przejrzyj naszą aktualną listę RFC.

Przegląd kodu

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

Przeglądanie kodu wniesionego do projektu, ponieważ pull requesty jest kluczowym elementem rozwoju TensorFlow. Zachęcamy każdego, aby zaczął przeglądać kod przesłany przez innych programistów, zwłaszcza jeśli jest to coś, z czego prawdopodobnie będziesz korzystać.

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

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

  • Czy zawiera 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, gdy tylko jest to możliwe? Czy dokumentacja wyświetla się prawidłowo?

  • Czy kod jest czytelny dla człowieka? Czy jest mało nadmiarowości? Czy nazwy zmiennych powinny zostać poprawione dla jasności lub spójności? Czy należy dodawać komentarze? Czy jakiekolwiek komentarze należy usuwać jako nieprzydatne lub nieistotne?

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

  • Czy kod jest wstecznie zgodny z poprzednimi wersjami TensorFlow?

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

Testuj i popraw zasięg testów

Wysokiej jakości testy jednostkowe to podstawa procesu rozwoju TensorFlow. W tym celu wykorzystujemy obrazy Docker. Funkcje testowe są odpowiednio nazwane i odpowiadają za sprawdzanie poprawności algorytmów oraz różnych opcji kodu.

Wszystkie nowe funkcje i poprawki błędów muszą obejmować odpowiednie pokrycie testami. Z zadowoleniem przyjmujemy również wkład nowych przypadków testowych lub ulepszeń do istniejących testów. Jeśli odkryjesz, że nasze istniejące testy nie są kompletne — nawet jeśli nie powoduje to aktualnie błędu — zgłoś problem i, jeśli to możliwe, zgłoś żądanie.

Aby uzyskać szczegółowe informacje na temat procedur testowania w każdym projekcie TensorFlow, zobacz 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 klasa są testowane?
  • Czy przetestowano rozsądny zestaw parametrów , ich wartości, typy wartości i kombinacje?
  • Czy testy sprawdzają, czy kod jest poprawny i czy robi to, co dokumentacja mówi, że kod jest przeznaczony?
  • Jeśli zmiana jest poprawką błędu, czy uwzględniono test bez regresji ?
  • Czy testy przechodzą kompilację ciągłej integracji ?
  • Czy testy obejmują każdy wiersz kodu? Jeśli nie, to czy wyjątki są rozsądne i jednoznaczne?

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

Popraw komunikaty o błędach lub logi

Czekamy na wkłady, które poprawiają komunikaty o błędach i rejestrowanie.

Przepływ pracy

Wkład kodu — poprawki błędów, nowe programy deweloperskie, ulepszenia testów — wszystko odbywa się zgodnie z przepływem pracy skoncentrowanym na GitHub. Aby uczestniczyć w rozwoju TensorFlow, załóż konto GitHub. Następnie:

  1. Rozwiń repozytorium, nad którym planujesz pracować. Przejdź do strony repozytorium projektu i użyj przycisku rozwidlenia . Spowoduje to utworzenie kopii repozytorium pod Twoją nazwą użytkownika. (Aby uzyskać więcej informacji na temat forkowania repozytorium, zobacz ten przewodnik .)

  2. Sklonuj repozytorium do systemu lokalnego.

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

  3. Utwórz nowy oddział do przechowywania swojej pracy.

    $ git checkout -b new-branch-name

  4. Pracuj nad nowym kodem. Napisz i uruchom testy.

  5. Zatwierdź swoje zmiany.

    $ git add -A

    $ git commit -m "commit message here"

  6. Prześlij zmiany do repozytorium GitHub.

    $ git push origin branch-name

  7. Otwórz żądanie ściągnięcia (PR). Przejdź do oryginalnego repozytorium projektu na GitHub. Pojawi się komunikat o ostatnio wypchniętym branchu z pytaniem, czy chcesz otworzyć pull request. Postępuj zgodnie z instrukcjami, porównaj repozytoria i prześlij PR. Spowoduje to wysłanie e-maila do autorów. Możesz rozważyć wysłanie e-maila 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 przejrzą Twój PR . Weź udział w rozmowie i spróbuj wprowadzić żądane zmiany . Po zatwierdzeniu PR kod zostanie scalony.

Zanim zaczniesz pracować nad kolejnym wkładem , upewnij się, że lokalne repozytorium jest aktualne.

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

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

  2. Przełącz się na lokalną gałąź master.

    $ git checkout master

  3. Pociągnij zmiany z wcześniejszych.

    $ git pull upstream master

  4. Prześlij zmiany na swoje konto GitHub. (Opcjonalne, ale dobra praktyka).

    $ git push origin master

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

    $ git checkout -b branch-name

Dodatkowe zasoby git i GitHub:

Lista kontrolna kontrybutora