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):
- 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 pojedynczą umowę licencyjną na treści.
- Jeśli pracujesz w firmie, musi ona przesłać Umowę licencyjną dotyczącą firmy, aby potwierdzić, że możesz przekazywać swoje prace do tej biblioteki klienta.
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:
- Podpisz Umowę licencyjną dla współtwórcy w sposób opisany powyżej.
- Dołącz do naszej grupy dyskusyjnej.
- Skonfiguruj środowisko programistyczne.
- 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.
- 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.
- 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
- Zainstaluj Java 6. Może być konieczne ustawienie zmiennej
JAVA_HOME
. - Zainstaluj narzędzie Maven. (W tym dokumencie zakładamy, że znasz już podstawowe polecenia Maven).
- Opcjonalnie: zainstaluj Android SDK i ustaw w zmiennej ANDROID_Home lokalizację instalacji dla Androida.
- 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ć:
- Uruchom Eclipse i wybierz Window > Android SDK Manager lub uruchom
android
w wierszu poleceń. - 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:
- google-http-java-client
- google-oauth-java-client
- 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:
- Otwórz zgłoszenie na stronie codereview.appspot.com.
- Poprawkę, której dotyczy problem, poszukaj w prawym górnym rogu specyfikacji poprawki i poszukaj opcji „Pobierz nieprzetworzoną”.
- Kliknij „raw”, aby uzyskać adres URL pliku do zaimportowania.
- Zapisz nieprzetworzony plik diff na komputerze lokalnym pod nazwą np.issue123456.diff.
- 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 jakoauthor
(--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ć:
- Wybierz problem na codereview.appspot.com.
- 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 -- .