Jak dołączyć do projektu

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Umowy licencyjne (współtwórcy)

Zanim przyjmiemy poprawki poprawek, musisz przesłać osobę lub korporacyjną umowę licencyjną na treści w ramach programu Contributor:

  • Jeśli jesteś osobą, która pisze oryginalny kod źródłowy, i masz pewność, że jesteś właścicielem własności intelektualnej, prześlij indywidualną CLA.
  • Jeśli pracujesz dla firmy, Twoja firma musi przesłać korporacyjną listę CLA, aby wskazać, że możesz dodawać swoje prace do tej biblioteki klienta.

Otwórz jeden z 2 linków powyżej, aby uzyskać dostęp do odpowiedniej CLA i instrukcji, jak ją podpisać i zwrócić. Gdy go otrzymamy, dodamy Cię do oficjalnej listy współtwórców.

Omówienie przesyłania poprawek

Aby dodać kod do tego projektu, wykonaj te ogólne kroki:

  1. Podpisz umowę licencyjną na usługę Contributor zgodnie z opisem powyżej.
  2. Dołącz do naszej grupy dyskusyjnej.
  3. Skonfiguruj środowisko programistyczne.
  4. Powiąż każdą z zbiorów danych z problemem (raportem o błędzie lub prośbą o dodanie funkcji) w naszym narzędziu do śledzenia błędów GitHuba. Utwórz nowy problem, jeśli jeszcze go nie masz, i przypisz go do siebie.
  5. Sprawdź kod, utwórz nowy problem na codereview.appspot.com i dokończ proces weryfikacji kodu. Szczegółowe instrukcje dotyczące wszystkich tych procesów znajdziesz poniżej.
  6. Gdy kod zostanie sprawdzony i otrzymasz zgodę, zatwierdź go. Jeśli nie jesteś oficjalnym współtwórcy, współtwórca pobiera zmiany w oficjalnym repozytorium.

Korzystamy z tych narzędzi i procesów:

  • Jako systemu kontroli wersji korzystamy Git.
  • W systemie kompilacji używamy systemu Maven, a także systemu dystrybucji binarnej.
  • Do weryfikacji kodu używamy kodu codereview.appspot.com. (Pamiętaj jednak, że w narzędziu codereview.appspot.com termin „"issue"” oznacza prośbę o sprawdzenie kodu, a w narzędziu Issue Tracker „"issue"” to żądanie funkcji lub raport o błędzie).

Jeśli jesteś deweloperem Eclipse, użyj formatowania kodu dla projektu 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 Maven. W tym dokumencie założono, że znasz podstawowe informacje o poleceniach Maven.
  3. Opcjonalnie: zainstaluj pakiet SDK do Androida i ustaw zmienną ANDROID_HOME na lokalizację instalacji Androida.
  4. Zainstaluj Git.

Konfiguruję Git

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

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

Uwierzytelnianie przy użyciu GitHuba z Git

Aby móc przeglądać kod na GitHubie, musisz uwierzytelnić się w GitHubie przy użyciu HTTP lub SSH. Zanim wykonasz poniższe instrukcje, zapoznaj się z instrukcjami GitHuba dotyczącymi rozpoczynania klonowania protokołu HTTPS lub SSH. Więcej ogólnych informacji o Git znajdziesz w artykule Pro Git.

Sprawdzam kod

Używanie HTTPS

Aby sprawdzić repozytorium biblioteki w gałęzi programisty i katalogu nadrzędnego, uruchom to polecenie:

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

Przez SSH

Aby sprawdzić repozytorium biblioteki w gałęzi programowania i premium, 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 alternatywną gałąź, na przykład 1.12:

git checkout --track origin/1.12

Aby przełączyć się z powrotem do gałęzi nadrzędnej:

git checkout master

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

git pull

Maven

Instalowanie Usług Google Play

Podczas pierwszej konfiguracji projektu musisz zainstalować plik google-play-services.jar. Aby wysłać prośbę o skonfigurowanie konta:

  1. Uruchom Eclipse i wybierz okno > Android SDK Manager lub uruchom android z poziomu wiersza poleceń.
  2. Przewiń do dołu listy pakietów i wybierz Dodatki i 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). Wyszukiwanie plików binarnych w tym repozytorium przed pobraniem z centralnego repozytorium Maven.

Uwaga: zawartość tej biblioteki zależy od klienta google-http-java-client i google-oauth-java-client. Gdy pracujesz nad nową wersją wszystkich 3 bibliotek, które nie są jeszcze udostępnione 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 Kompilacja w tej kolejności pozwala Maven na pobieranie skompilowanych plików binarnych na potrzeby kompilacji biblioteki zależnej.

Proces sprawdzania kodu

Pobieranie skryptu Upload.py

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

Przy pierwszym uruchomieniu upload.py poprosi o 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

Przed wysłaniem kodu do sprawdzenia musisz uruchomić Clirr, by wykryć w nim problemy ze zgodnością wsteczną. Jeśli wystąpią błędy, musisz je poprawić lub zaktualizować plik clirr-ignored-differences.xml.

mvn -q clirr:check

Aby wykryć błędy w kodzie, musisz też uruchomić narzędzie Znajdź. Jeśli wystąpią błędy, musisz je poprawić lub zaktualizować plikfindbugs-exclude.xml. (Pamiętaj, że usługa Znajdź rozwiązanie jest bardzo powolna).

mvn findbugs:check

Gdy zmiana przejdzie wszystkie testy, dodaj ją do indeksu (obszar testowy Git):

git add .

Upewnij się, że wszystkie dodane, zmodyfikowane lub usunięte pliki są odzwierciedlane w indeksie:

git status

W danych wyjściowych strony git status sprawdź sekcję o nazwie &"Zmiany do zatwierdzenia."

Rozpoczynanie weryfikacji kodu

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

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

Po wprowadzeniu większej liczby zmian wprowadź zmiany. Aby przesłać nową poprawkę, na przykład wysłać numer 123456, uruchom to polecenie:

upload.py --rev=HEAD -i 123456

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

Jeśli wolisz typowe przepływy pracy w GitHub, prawdopodobnie masz rozwinięty repozytorium GitHub i utworzono gałąź tej nowej funkcji lub poprawki błędu. Gdy wysyłasz prośby o sprawdzenie kodu z własnego rozwidlenia, upewnij się, że rozwidlenie jest zsynchronizowane z repozytorium nadrzędnego. Więcej informacji znajdziesz w artykule o synchronizowaniu rozwidlenia na GitHubie.

Możesz też użyć pliku Upload.py na potrzeby lokalnych zmian.

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

Kontroler kodu

Jeśli jesteś weryfikatorem kodu, zaimportuj i przetestuj zbiory zmian przed ich zatwierdzeniem, a następnie zatwierdź i przekaż zestawy zmian do zdalnego repozytorium.

Importowanie zestawu zmian

Aby wcześnie wykryć błędy, pobierz najnowsze zmiany ze zdalnego repozytorium do drzewa roboczego. Upewnij się, że drzewo robocze jest czyste, a indeks jest pusty.

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

git pull

Aby sprawdzić, co w drzewie i indeksie działa:

git status

Aby zaimportować poprawkę do lokalnego klonu Git:

  1. Otwórz problem na stronie codereview.appspot.com.
  2. Aby znaleźć odpowiedni poprawkę, w prawym górnym rogu specyfikacji poprawki znajdź polecenie "Download raw".
  3. Kliknij "raw", aby uzyskać adres URL pliku, który chcesz zaimportować.
  4. Zapisz nieprzetworzony plik różnicy na komputerze lokalnym o nazwie np. issue123456.diff.
  5. Przejdź do lokalnego działającego drzewa Git i zastosuj różnicę za pomocą polecenia patch:
patch -p1 < issue123456.diff

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

Testowanie zestawu zmian

Aby przeprowadzić testy i zainstalować, użyj tego polecenia:

mvn clean install checkstyle:check

Zatwierdzanie zestawu zmian na codecode.appspot.com

Ogólnie kod nie może zostać przekazany do repozytorium GitHub, dopóki weryfikator nie będzie zadowolony, że kod jest gotowy. Na konwencji odpowiada się komunikatem „LGTM” (w porządku).

Zatwierdzanie kodu

Ważne: przed zatwierdzeniem kodu pobierz najnowsze zmiany do drzewa roboczego i zaktualizuj drzewo robocze do najnowszego zatwierdzenia z repozytorium GitHub:

git pull

Jeśli wystąpią konflikty, rozwiąż je, a następnie zadbaj o to, aby wszystkie testy zostały zaliczone.

Aby zatwierdzić kod lokalnie: 

git commit

Wpisz taki komunikat (zakładając, że naprawiasz lub wdrażasz problem nr 123, jak podano w narzędziu do śledzenia błędów GitHuba):

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

Przed pierwszym dwukropkiem i opisem:

  • Jeśli to rozwiązanie problemu w Trackerze problemów, podaj numer problemu, jak pokazano poniżej.
  • Jeśli jest to zmiana dla określonej gałęzi, podaj jej numer.
  • Stanowią one committer tego zatwierdzenia, jednak należy podać autorowi zmiany, oznaczając je jako author (--author=<author>).

Zgodnie z opisem zawsze umieszczaj link do problemu w witrynie Codereview. Ten link jest ważny, ponieważ bez niego nie ma wygodnego sposobu na sprawdzenie kodu powiązanego z zatwierdzeniem, co jest przydatne do prowadzenia historii dyskusji.

Aby przenieść zmianę do repozytorium GitHub:

git push

Jeśli podczas gry git push pojawi się komunikat o błędzie informujący o odrzuceniu aktualizacji (np. gdy nie korzystasz z git pull), możesz połączyć te zmiany 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 sprawdzania kodu. Aby wysłać prośbę o skonfigurowanie konta:

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

Wycofywanie usunięcia zestawu zmian

Jeśli z jakiegoś powodu postanowisz nie importować importowanego zestawu zmian, użyj tego polecenia, aby go usunąć. Zachowaj ostrożność: powoduje to usunięcie wszystkich lokalnych zmian. 

git checkout -- .