Jak dołączyć do projektu

Umowy licencyjne dla twórców (CLA)

Zanim będziemy mogli przyjąć Twoje poprawki kodu, musisz przesłać umowę licencyjną dla współtwórców lub firmową umowę licencyjną współtwórcy (CLA):

Aby otworzyć odpowiednią umowę licencyjną na treści oraz instrukcje, jak ją podpisać i zwrócić, kliknij jeden z 2 linków powyżej. Gdy go otrzymamy, będziemy mogli dodać Cię do oficjalnej listy współtwórców.

Omówienie przesyłania poprawek

Aby dodać kod do tego projektu, wykonaj te ogólne czynności:

  1. Podpisz Umowę licencyjną dla współtwórcy w sposób opisany powyżej.
  2. Dołącz do naszej grupy dyskusyjnej.
  3. Skonfiguruj środowisko programistyczne.
  4. Powiąż każdy zestaw zmian z konkretnym problemem (raportem o błędzie lub prośbą o dodanie funkcji) w naszym narzędziu do śledzenia problemów na GitHubie. Utwórz nowy problem, jeśli jeszcze go nie ma, i przypisz go do siebie.
  5. Sprawdź kod, utwórz nowy problem na stronie codereview.appspot.com i zakończ proces weryfikacji kodu. Szczegółowe instrukcje dotyczące wszystkich tych procesów znajdziesz poniżej.
  6. Gdy kod zostanie sprawdzony i otrzymasz zatwierdzenie, zatwierdź go. Jeśli nie jesteś oficjalnym Współtwórcą, współtwórca pobierze Twój zestaw zmian do oficjalnego repozytorium.

Używamy tych narzędzi i procesów:

  • Używamy Git jako systemu kontroli wersji.
  • Do systemów kompilacji oraz binarnego systemu dystrybucji używamy Maven.
  • Do weryfikacji kodu używamy domeny codereview.appspot.com. (Zwróć jednak uwagę, że w narzędziu codereview.appspot.com „problem” oznacza prośbę o sprawdzenie kodu, a w narzędziu GitHub Issue Tracker „problem” to prośba o dodanie funkcji lub raport o błędzie).

Jeśli jesteś programistą Eclipse, użyj odpowiedniego dla projektu formatowania określonego w katalogu .settings, który jest automatycznie przetwarzany przez Eclipse.

Konfigurowanie środowiska programistycznego

Wymagania wstępne

  1. Zainstaluj Java 6. Może być konieczne ustawienie zmiennej JAVA_HOME.
  2. Zainstaluj narzędzie Maven. (W tym dokumencie zakładamy, że znasz już podstawowe polecenia Maven).
  3. Opcjonalnie: zainstaluj Android SDK i ustaw w zmiennej ANDROID_Home lokalizację instalacji dla Androida.
  4. Zainstaluj Git.

Konfiguruję Git

Aby ustawić domyślną wyświetlaną nazwę i adres e-mail, użyj polecenia git config:

git config --global user.name "YOUR NAME"
git config --global user.email "YOUR EMAIL ADDRESS"

Uwierzytelnianie na GitHubie z Git

Aby zobaczyć kod z GitHuba, musisz uwierzytelnić się w GitHubie za pomocą protokołu HTTP lub SSH. Zanim wykonasz podane niżej instrukcje, przeczytaj na GitHubie instructions, jak zacząć korzystać z klonowania HTTPS lub SSH. Jeśli chcesz ogólnie dowiedzieć się więcej o Gicie, zajrzyj do Pro Git.

Sprawdzanie kodu

Korzystanie z protokołu HTTPS

Aby sprawdzić repozytorium biblioteki w gałęzi głównej programistycznej, uruchom to polecenie:

git clone https://github.com/google/google-api-java-client.git

Przy użyciu SSH

Aby sprawdzić repozytorium biblioteki w gałęzi głównej, upewnij się, że masz uprawnienia do zapisu w repozytorium GitHub, a następnie uruchom to polecenie:

git clone git@github.com:google/google-api-java-client.git

Aby przełączyć się na gałąź alternatywną, na przykład 1.12:

git checkout --track origin/1.12

Aby przełączyć się z powrotem do gałęzi głównej:

git checkout master

Aby pobrać najnowsze zmiany z repozytorium GitHub i zaktualizować lokalne drzewo robocze do najnowszego zatwierdzenia:

git pull

Maven

Zainstaluj Usługi Google Play

Podczas konfigurowania projektu po raz pierwszy musisz zainstalować plik google-play-services.jar. Aby to zrobić:

  1. Uruchom Eclipse i wybierz Window > Android SDK Manager lub uruchom android w wierszu poleceń.
  2. Przewiń w dół listy pakietów i wybierz Dodatki > Usługi Google Play.
mvn install:install-file \
           -Dfile=$ANDROID_HOME/extras/google/google_play_services/libproject/google-play-services_lib/libs/google-play-services.jar \
           -DgroupId=com.google.android.google-play-services \
           -DartifactId=google-play-services \
           -Dversion=1 \
           -Dpackaging=jar

Kompilowanie projektu

mvn clean install

Maven instaluje skompilowane pliki binarne w lokalnym repozytorium (na przykład ~/.m2/repository). Wyszukuje pliki binarne w tym repozytorium przed pobraniem z centralnego repozytorium Maven.

Uwaga: ta biblioteka zależy od klienta google-http-java-client i google-oauth-java-client. Podczas pracy nad nową wersją wszystkich 3 bibliotek, które nie są jeszcze dostępne w centrum Maven, musisz skompilować je w tej kolejności:

  1. google-http-java-client
  2. google-oauth-java-client
  3. google-api-java-client Dzięki kompilacji w tej kolejności Maven może pobrać skompilowane pliki binarne na potrzeby kompilacji zależnych.

Proces weryfikacji kodu

Pobieranie skryptu send.py

Pobierz skrypt upload.py i opcjonalnie dodaj go do ścieżki PATH.

Przy pierwszym uruchomieniu aplikacji upload.py pojawi się prośba o podanie hasła aplikacji:

Email (login for uploading to codereview.appspot.com): your_email_address@yourdomain.com
Password for your_email_address@yourdomain.com: 

Przygotowanie kodu do sprawdzenia

Zanim wyślesz kod do sprawdzenia, musisz uruchomić Clirr, aby wykryć w nim problemy ze zgodnością wsteczną. Jeśli zostaną zgłoszone błędy, musisz je poprawić lub zaktualizować plik clirr-ignored-differences.xml.

mvn -q clirr:check

Musisz też uruchomić narzędzie FindBugs, aby wychwycić błędy w kodzie. Jeśli zostaną zgłoszone błędy, musisz je naprawić lub zaktualizować plik findbugs-excl.xml. (Pamiętaj, że funkcja Znajdź błędy jest bardzo powolna).

mvn findbugs:check

Gdy zmiana przejdzie wszystkie testy, dodaj ją do indeksu (obszaru testowania Git):

git add .

Dokładnie sprawdź, czy wszystkie pliki dodane, zmodyfikowane lub usunięte są uwzględnione w indeksie:

git status

W danych wyjściowych git status sprawdź sekcję „Zmiany do zatwierdzenia”.

Rozpoczynanie weryfikacji kodu

Gdy wszystko będzie gotowe do sprawdzenia, utwórz nowy problem na stronie codereview.appspot.com:

upload.py --rev=HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...

Gdy wprowadzisz więcej zmian, wprowadź je stopniowo. Aby przesłać nową poprawkę, na przykład numer problemu 123456, uruchom to polecenie:

upload.py --rev=HEAD -i 123456

Aby wyświetlić więcej opcji, uruchom upload.py --help.

Jeśli wolisz typowy przepływ pracy na GitHubie, prawdopodobnie rozwiniesz repozytorium GitHub i utworzysz gałąź dla tej nowej funkcji lub poprawki błędu. Gdy wysyłasz żądania weryfikacji kodu z własnego rozwidlenia, upewnij się, że jego rozwidlenie jest zsynchronizowane z repozytorium nadrzędnym. Więcej informacji znajdziesz w pomocy GitHuba na temat tego, jak synchronizować widelec.

Możesz użyć pliku send.py także w przypadku zatwierdzonych lokalnie zestawów zmian.

upload.py --rev=upstream/master:HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...

Weryfikator kodu

Jeśli jesteś weryfikatorem kodu, zaimportuj i przetestuj zestawy zmian, zanim je zatwierdzisz, a następnie zatwierdź i przekaż zestawy zmian do zdalnego repozytorium.

Importowanie zbioru zmian

Aby wcześnie wychwycić błędy, pobierz najnowsze zmiany ze zdalnego repozytorium do drzewa roboczego. Sprawdź, czy drzewo robocze jest czyste, a indeks pusty.

Aby pobrać i scalić najnowsze zatwierdzenia z repozytorium zdalnego:

git pull

Aby sprawdzić zawartość drzewa roboczego i indeksu:

git status

Aby zaimportować poprawkę do lokalnego klonu Git:

  1. Otwórz zgłoszenie na stronie codereview.appspot.com.
  2. Poprawkę, której dotyczy problem, poszukaj w prawym górnym rogu specyfikacji poprawki i poszukaj opcji „Pobierz nieprzetworzoną”.
  3. Kliknij „raw”, aby uzyskać adres URL pliku do zaimportowania.
  4. Zapisz nieprzetworzony plik diff na komputerze lokalnym pod nazwą np.issue123456.diff.
  5. Otwórz lokalne drzewo robocze Git i zastosuj różnice za pomocą polecenia patch:
patch -p1 < issue123456.diff

Aby upewnić się, że zaimportowana została prawidłowa różnica, wykonaj polecenie git diff w drzewie roboczym.

Testowanie zbioru zmian

Aby uruchomić testy i zainstalować aplikację, użyj tego polecenia:

mvn clean install checkstyle:check

Zatwierdzanie zbioru zmian na stronie codereview.appspot.com

Ogólnie kodu nie można przekazać do repozytorium GitHub, dopóki weryfikator nie uzna, że jest on gotowy. Zgodnie z konwencją należy wysłać odpowiedź „LGTM” (Looks Good To Me).

Zatwierdzanie kodu

Ważne: zanim zatwierdzisz kod, pobierz najnowsze zmiany do drzewa roboczego i zaktualizuj je do najnowszego zatwierdzenia z repozytorium GitHub:

git pull

Jeśli wystąpią jakieś konflikty, rozwiąż je i zadbaj o to, aby wszystkie testy były ponownie zaliczone.

Aby zatwierdzić kod lokalnie:

git commit

Wpisz komunikat podobny do tego (zakładając, że naprawiasz lub implementujesz problem nr 123 podany w narzędziu do śledzenia problemów na GitHubie):

#123: NullPointerException when passing null to processFoo()
http://codereview.appspot.com/123456/

Przed pierwszym dwukropkiem i opisem:

  • Jeśli błąd został rozwiązany w narzędziu Issue Tracker, podaj numer problemu, jak pokazano na ilustracji.
  • Jeśli jest to zmiana w konkretnej gałęzi, podaj numer oddziału.
  • Ty będziesz committer tego zobowiązania, ale podaj autora zmiany, oznaczając go jako author (--author=<author>).

Pod opisem problemu zawsze umieszczaj link do problemu w witrynie weryfikacji kodu. Ten link jest ważny, ponieważ bez niego nie da się w wygodny sposób zaplanować weryfikacji kodu powiązanej z zatwierdzeniem, co jest przydatne do podtrzymywania historii dyskusji.

Aby przekazać zmianę do repozytorium GitHub:

git push

Jeśli w trakcie git push pojawi się komunikat o błędzie z informacją o odrzuceniu aktualizacji (być może zapomniałeś uruchomić git pull), wykonaj poniższe czynności, aby scalić je z najnowszymi zmianami i przekazać je do zdalnego repozytorium:

git pull
git commit
git push

Zamykanie problemu

Pamiętaj, aby zamknąć problem w narzędziu do weryfikacji kodu. Aby to zrobić:

  1. Wybierz problem na codereview.appspot.com.
  2. Kliknij „X” w lewym górnym rogu przed znakiem „Identyfikator”.

Usuwanie poprawek zbioru zmian

Jeśli z jakiegoś powodu nie chcesz zatwierdzić zaimportowanego zbioru zmian, pozbądź się go za pomocą tego polecenia. Uważaj: spowoduje to usunięcie wszystkich lokalnych zmian.

git checkout -- .