Jak dołączyć do projektu

Umowy licencyjne dla współtwórców (CLA)

Zanim będziemy mogli zaakceptować poprawki kodu, musisz przesłać lub korporacyjną umowę licencyjną współtwórcy (CLA):

  • Jeśli jesteś osobą tworzącą oryginalny kod źródłowy i masz pewność, że jesteś właścicielem własności intelektualnej, prześlij własna umowa CLA.
  • Jeśli pracujesz w firmie, musi ona przesłać własną umowę CLA. aby wskazać, że możesz przesyłać swoje prace do tej biblioteki klienta.

Kliknij dowolny z powyższych linków, aby uzyskać dostęp do odpowiedniej CLA i instrukcje jego podpisania i oddania. Gdy ją otrzymamy, będziemy mogli Cię dodać do oficjalnej listy współtwórców.

Omówienie przesyłania poprawek

Aby współtworzyć kod w tym projekcie, wykonaj te ogólne czynności:

  1. Podpisz Umowę licencyjną dla współtwórców w sposób opisany powyżej.
  2. Dołącz do naszej grupy dyskusyjnej.
  3. Skonfiguruj środowisko programistyczne.
  4. Powiąż każdy zbiór zmian z problemem (raportem o błędzie lub funkcją) ) w naszym narzędziu do śledzenia problemów w 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 dokończ proces weryfikacji kodu. Poniżej podajemy szczegółowe instrukcje dotyczące wszystkich tych procesów.
  6. Gdy kod zostanie sprawdzony i zaakceptowany, zatwierdź go. Jeśli nie jesteś oficjalnym współtwórcą, pobierze on Twój zestaw zmian do oficjalnego repozytorium.

Używamy następujących narzędzi i procesów:

  • Nasz system kontroli wersji to Git.
  • Na potrzeby systemu kompilacji używamy Maven. na binarnym systemie dystrybucji.
  • Do tworzenia kodu używamy domeny codereview.appspot.com opinie. (Zwróć jednak uwagę, że w narzędziu codereview.appspot.com słowo „issue” oznacza żądanie weryfikacji kodu, natomiast w narzędziu GitHub Issue Tracker jest prośba o dodanie funkcji lub raport o błędzie).

Jeśli jesteś programistą Eclipse, użyj formatowania kodu związanego z projektem określony 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 urządzenia JAVA_HOME .
  2. Zainstaluj Maven. (Ten dokument zakładamy, że dysponujesz podstawową znajomością poleceń Maven).
  3. Opcjonalnie: zainstaluj pakiet SDK do Androida. i ustaw zmienną ANDROID_HOME na lokalizację instalacji na Androidzie.
  4. Zainstaluj Git.

Konfigurowanie 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 w usłudze GitHub z Git

Aby zobaczyć kod z GitHuba, musisz się uwierzytelnić za pomocą GitHub przy użyciu HTTP lub SSH. Zanim przejdziesz do poniższych instrukcji znajdziesz w serwisie GitHub tutaj znajdziesz instrukcje, klonowano od HTTPS lub SSH. Jeśli chcesz dowiedzieć się więcej o Git in Pro Git jest dobrym materiałem.

Sprawdzam kod

Przy użyciu protokołu HTTPS

Aby zapoznać się z repozytorium biblioteki w programie głównym, gałąź, uruchom następujące polecenie:

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

Używanie SSH

Aby zapoznać się z repozytorium biblioteki w programie głównym, gałąź, zrób upewnij się, że mieć 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 inną gałąź, na przykład 1.12:

git checkout --track origin/1.12

Aby przełączyć się z powrotem na gałąź główną:

git checkout master

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

git pull

Maven

Zainstaluj Usługi Google Play

Przy pierwszej konfiguracji projektu musisz zainstalować google-play-services.jar. Aby to zrobić:

  1. Uruchom Eclipse i wybierz Okno > Android SDK Manager lub uruchom android. w wierszu poleceń.
  2. Przewiń do dołu listy pakietów i wybierz Dodatki > Google Play, usługi.
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 do lokalnego repozytorium (na przykład ~/.m2/repozytorium). Przed pobraniem wyszukuje pliki binarne w tym repozytorium z centralnego repozytorium Maven.

Uwaga: Ta biblioteka korzysta z pakietu google-http-java-client oraz google-oauth-java-client. Podczas pracy nad nową wersją wszystkich 3 bibliotek, które nie zostały jeszcze opublikowane do Maven, musisz skompilować je w tej kolejności:

  1. google-http-java-client
  2. google-oauth-java-client
  3. google-api-java-client Kompilacja w tej kolejności daje pewność, że Maven pobierze skompilowane pliki binarne dla kompilację bibliotek zależnych.

Proces weryfikacji kodu

pobieranie skryptu send.py

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

Przy pierwszym uruchomieniu aplikacji upload.py zobaczysz prośbę o podanie hasło 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 wychwytywać dane wstecz na problemy ze zgodnością w kodzie. Jeśli zostaną zgłoszone błędy, albo je napraw lub zaktualizuj plik clirr-ignored-differences.xml.

mvn -q clirr:check

Musisz też uruchomić narzędzie FindBugs, aby wyłapać błędy w kodzie. Jeśli wystąpią błędy musisz naprawić błędy lub zaktualizować plik findbugs-exclusion.xml. . Pamiętaj, że funkcja FindBugs działa bardzo wolno.

mvn findbugs:check

Gdy zmiana przejdzie wszystkie testy, dodaj ją do indeksu (plik przejściowy Git obszar:

git add .

Dokładnie sprawdź, czy wszystkie dodane, zmodyfikowane lub usunięte pliki zostały 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 kolejne zmiany, przeprowadź ich edycję. Aby przesłać nową poprawkę, na przykład, aby podać numer 123456, uruchom to polecenie: 

upload.py --rev=HEAD -i 123456

Aby zobaczyć więcej opcji, uruchom upload.py --help.

Jeśli wolisz typowy GitHub proces, prawdopodobnie masz rozwidlenie repozytorium GitHub i utworzenie gałęzi dla tej nowej funkcji lub poprawki błędu. Gdy wyślij kod Sprawdź żądania z własnego widelca, upewnij się, że jest on zsynchronizowany z do repozytorium nadrzędnego. Więcej informacji znajdziesz w pomocy GitHuba jak synchronizować widelec.

Możesz też użyć polecenia send.py również w przypadku zbiorów zmian zatwierdzonych lokalnie.

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 zbiory zmian przed ich zatwierdzeniem. a następnie zatwierdź i wypchnij zbiory zmian do repozytorium zdalnego.

Importowanie zbioru zmian

Aby wcześniej wychwytywać błędy, pobierz najnowsze zmiany ze pilota w drzewie roboczym. Upewnij się, że drzewo jest czyste indeks jest pusty.

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

git pull

Aby sprawdzić, co znajduje się w drzewie roboczym i indeksie:

git status

Aby zaimportować poprawkę do lokalnego klonu Git:

  1. Otwórz problem na stronie codereview.appspot.com.
  2. W przypadku danej poprawki poszukaj komunikatu „Pobierz nieprzetworzone” w prawym górnym rogu specyfikacji poprawki.
  3. Kliknij „Nieprzetworzone”. aby uzyskać adres URL pliku do zaimportowania.
  4. Zapisz plik nieprzetworzonej różnicy na komputerze lokalnym pod nazwą issue123456.diff.
  5. Przejdź do lokalnego drzewa roboczego Git i zastosuj różnice za pomocą interfejsu patch polecenie:
patch -p1 < issue123456.diff

Aby upewnić się, że zostały zaimportowane właściwe różnice, git diff w drzewie roboczym.

Testowanie zbioru zmian

Aby uruchomić testy i zainstalować, użyj następującego polecenia:

mvn clean install checkstyle:check

Zatwierdzanie zbioru zmian na stronie codereview.appspot.com

Zasadniczo nie można przekazać kodu do repozytorium GitHub, dopóki weryfikator kodu nie jest zadowolony, że kod jest gotowy. Zgodnie z tradycją należy odpowiadać z komunikatem „LGTM” (wygląda dobrze).

Zatwierdzanie kodu

Ważne: zanim zatwierdzisz kod, pobierz najnowsze zmiany do pliku drzewo robocze i zaktualizuj drzewo robocze do najnowszego zatwierdzenia z GitHuba repozytorium:

git pull

Jeśli wystąpiły konflikty, rozwiąż je, a następnie pilnuj, by wszystkie testy mogą znowu przejść weryfikację.

Aby zatwierdzić kod lokalnie: 

git commit

Wpisz komunikat podobny do tego (przy założeniu, że naprawiasz lub wprowadzasz zmiany Problem nr 123 podany w serwisie GitHub Issue Tracker):

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

Przed pierwszym dwukropkiem i opisem:

  • Jeśli to rozwiązanie problemu w narzędziu Issue Tracker, podaj jego numer w pokazanym przykładzie.
  • Jeśli jest to zmiana dla konkretnej gałęzi, podaj jej numer.
  • Będziesz committer tego zatwierdzenia, ale pochwal się autor zmiany, oznaczając go jako author (--author=<author>).

Zawsze podawaj link do problemu w weryfikacji kodu, postępując zgodnie z opisem. witrynie. Ten link jest ważny, ponieważ bez niego nie da się w wygodny sposób należy sprawdzić weryfikację kodu powiązaną z zatwierdzeniem. Jest to przydatne zachowywanie historii dyskusji.

Aby przekazać zmianę do repozytorium GitHub:

git push

Jeśli w czasie git push pojawi się komunikat o błędzie o odrzuceniu aktualizacji (może jeśli zapomniałeś uruchomić git pull), wykonaj te czynności, aby scalić te zmiany z najnowszymi zmianami wypchnij zmiany do zdalnego repozytorium: 

git pull
git commit
git push

Zakończenie problemu

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

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

Odinstalowywanie poprawek do zbioru zmian

Jeśli z jakiegoś powodu nie chcesz zatwierdzić zaimportowanego zestawu zmian, użyj metody następujące polecenie, aby go pozbyć. Zachowaj ostrożność: powoduje to dosłownie usunięcie wszystkich lokalnych zmian. 

git checkout -- .