Współtwórz kod TensorFlow

Niezależnie od tego, czy dodajesz funkcję strat, poprawiasz pokrycie testami, czy piszesz RFC dla istotnej zmiany w projekcie, ta część przewodnika dla współpracowników pomoże Ci zacząć. Dziękujemy za Twoją pracę i zainteresowanie ulepszaniem TensorFlow.

Zanim zaczniesz

Zanim prześlesz kod źródłowy do projektu TensorFlow, zapoznaj się z plikiem CONTRIBUTING.md w repozytorium GitHub projektu. Na przykład, zobacz plik CONTRIBUTING.md w głównym repozytorium TensorFlow. Wszyscy współautorzy kodu są zobowiązani do podpisania Umowy Licencyjnej Współtwórcy (CLA).

Aby uniknąć powielania pracy, prosimy o zapoznanie się z aktualnymi lub proponowanymi dokumentami RFC i kontakt z programistami na forach TensorFlow ( developers@tensorflow.org ) przed rozpoczęciem pracy nad nietrywialną funkcją. Jesteśmy dość wybiórczy w podejmowaniu decyzji o dodawaniu nowych funkcjonalności, a najlepszym sposobem na wniesienie wkładu i pomoc w projekcie jest praca nad znanymi problemami.

Problemy dla nowych współpracowników

Nowi współautorzy powinni szukać poniższych tagów podczas wyszukiwania pierwszego wkładu do bazy kodu TensorFlow. Zdecydowanie zalecamy, aby nowi współautorzy najpierw zajmowali się projektami „dobry pierwszy problem” i „mile widziany wkład”; pomoże to współautorowi zapoznać się z procesem pracy, a głównym programistom – poznać współautora.

Jeśli jesteś zainteresowany/a rekrutacją zespołu, który pomoże Ci uporać się z dużym problemem lub wprowadzić nową funkcję, wyślij wiadomość e-mail na adres grupy developers@ i zapoznaj się z naszą aktualną listą RFC.

Przegląd kodu

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

Przeglądanie kodu wnoszonego do projektu w formie pull requestów jest kluczowym elementem rozwoju TensorFlow. Zachęcamy każdego do zapoznania się z kodem przesłanym przez innych programistów, zwłaszcza jeśli ta funkcja jest czymś, 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 jest prawdopodobne, że będzie to używane? Czy Ty, jako użytkownik TensorFlow, podoba Ci się ta zmiana i zamierzasz z niej korzystać? Czy ta zmiana mieści się w zakresie TensorFlow? Czy koszt utrzymania nowej funkcji będzie adekwatny do korzyści?
  • Czy kod jest spójny 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 jasno udokumentowane? Czy nowe funkcjonalności są opisane w dokumentacji TensorFlow i zilustrowane przykładami, jeśli to możliwe? Czy dokumentacja renderuje się poprawnie?

  • Czy kod jest czytelny dla człowieka? Czy jest mało redundantny? Czy nazwy zmiennych powinny zostać poprawione, aby były bardziej przejrzyste i spójne? Czy należy dodać komentarze? Czy komentarze powinny zostać usunięte jako nieprzydatne lub zbędne?

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

  • Czy kod jest kompatybilny z poprzednimi wersjami TensorFlow?

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

Testowanie i poprawa pokrycia testowego

Wysokiej jakości testy jednostkowe stanowią fundament procesu rozwoju TensorFlow. W tym celu korzystamy z obrazów Dockera. Funkcje testowe mają odpowiednie nazwy i odpowiadają za sprawdzanie poprawności algorytmów oraz różnych opcji kodu.

Wszystkie nowe funkcje i poprawki błędów muszą obejmować odpowiednie testy. Chętnie przyjmiemy również nowe przypadki testowe lub ulepszenia istniejących testów. Jeśli okaże się, że nasze istniejące testy nie są kompletne — nawet jeśli nie powoduje to obecnie błędu — prosimy o zgłoszenie problemu i, jeśli to możliwe, o przesłanie pull requestu.

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

Szczególne obawy dotyczące odpowiedniego testowania budzą:

  • Czy każda funkcja i klasa publiczna jest sprawdzana?
  • Czy przetestowano rozsądny zestaw parametrów , ich wartości, typów wartości i kombinacji?
  • Czy testy weryfikują poprawność kodu i to, czy wykonuje on zadanie opisane w dokumentacji ?
  • Jeśli zmiana polega na naprawieniu błędu, czy uwzględniany jest test nieregresyjny ?
  • Czy testy przechodzą kompilację w ramach ciągłej integracji ?
  • Czy testy obejmują każdą linijkę kodu? Jeśli nie, czy wyjątki są uzasadnione i jasno określone?

Jeśli znajdziesz jakiekolwiek problemy, prosimy o pomoc autorowi w ich zrozumieniu i rozwiązaniu.

Popraw komunikaty o błędach lub dzienniki

Chętnie przyjmiemy sugestie, które pomogą udoskonalić komunikaty o błędach i rejestrowanie zdarzeń.

Przepływ pracy wkładu

Wkład w kod – poprawki błędów, nowe rozwiązania, usprawnienia testów – odbywa się zgodnie z procesem pracy opartym na GitHubie. Aby uczestniczyć w rozwoju TensorFlow, załóż konto GitHub. Następnie:

  1. Wykonaj fork 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 forkowania repozytorium znajdziesz w tym przewodniku ).

  2. Sklonuj repozytorium do lokalnego systemu.

    $ 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. Napisz i uruchom testy.

  5. Zatwierdź 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 GitHubie. Pojawi się komunikat o ostatnio wypchniętej gałęzi z pytaniem, czy chcesz otworzyć żądanie ściągnięcia. Postępuj zgodnie z instrukcjami, porównaj dane w repozytoriach i prześlij żądanie ściągnięcia. Spowoduje to wysłanie wiadomości e-mail do osób zatwierdzających zmiany. Możesz rozważyć wysłanie wiadomości e-mail na listę mailingową, aby zwiększyć widoczność. (Więcej informacji znajdziesz w przewodniku GitHub dotyczącym żądań ściągnięcia .)

  8. Opiekunowie i inni współautorzy przejrzą Twoje zgłoszenie (PR) . Prosimy o udział w dyskusji i wprowadzenie wszelkich żądanych zmian . Po zatwierdzeniu zgłoszenia (PR) kod zostanie scalony.

Zanim zaczniesz tworzyć kolejny wpis , upewnij się, że Twoje lokalne repozytorium jest aktualne.

  1. Skonfiguruj zdalne urządzenie nadrzędne. (Musisz to zrobić tylko raz w danym projekcie, a nie za każdym razem.)

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

  2. Przełącz się na lokalną gałąź główną.

    $ git checkout master

  3. Pobierz zmiany z głównego źródła.

    $ git pull upstream master

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

    $ git push origin master

  5. Utwórz nową gałąź, jeśli zaczynasz nową pracę.

    $ git checkout -b branch-name

Dodatkowe zasoby git i GitHub:

Lista kontrolna dla współautorów