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:
- Podpisz umowę licencyjną na usługę Contributor zgodnie z opisem powyżej.
- Dołącz do naszej grupy dyskusyjnej.
- Skonfiguruj środowisko programistyczne.
- 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.
- 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.
- 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
- Zainstaluj Java 6. Może być konieczne ustawienie zmiennej
JAVA_HOME
. - Zainstaluj Maven. W tym dokumencie założono, że znasz podstawowe informacje o poleceniach Maven.
- Opcjonalnie: zainstaluj pakiet SDK do Androida i ustaw zmienną ANDROID_HOME na lokalizację instalacji Androida.
- 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:
- Uruchom Eclipse i wybierz okno > Android SDK Manager lub uruchom
android
z poziomu wiersza poleceń. - 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:
- google-http-java-client
- google-oauth-java-client,
- 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:
- Otwórz problem na stronie codereview.appspot.com.
- Aby znaleźć odpowiedni poprawkę, w prawym górnym rogu specyfikacji poprawki znajdź polecenie "Download raw".
- Kliknij "raw", aby uzyskać adres URL pliku, który chcesz zaimportować.
- Zapisz nieprzetworzony plik różnicy na komputerze lokalnym o nazwie np. issue123456.diff.
- 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 jakoauthor
(--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:
- Wybierz problem na stronie codereview.appspot.com.
- Kliknij „X” w lewym górnym rogu, przed „"Id."”.
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 -- .