Lizenzvereinbarungen für Mitwirkende
Bevor wir Ihre Code-Patches annehmen können, müssen Sie entweder eine natürliche Person oder eine unternehmensspezifische Lizenzvereinbarung für Mitwirkende einreichen:
- Wenn Sie als Einzelperson Originalquellcode schreiben und sicher sind, dass Sie Inhaber des geistigen Eigentums sind, reichen Sie eine individuelle CLA ein.
- Wenn Sie für ein Unternehmen arbeiten, muss Ihr Unternehmen ein CLA für Unternehmen einreichen, um anzugeben, dass Sie Ihre Arbeit zu dieser Clientbibliothek beitragen dürfen.
Klicken Sie auf einen der beiden obigen Links, um das entsprechende CLA aufzurufen und eine Anleitung zur Unterzeichnung und Einreichung zu erhalten. Sobald wir sie erhalten haben, können wir Sie zur offiziellen Liste der Mitwirkenden hinzufügen.
Übersicht über das Einreichen von Patches
Gehen Sie so vor, um Code zu diesem Projekt beizusteuern:
- Unterzeichnen Sie wie oben beschrieben eine Mitwirkende-Lizenzvereinbarung.
- Treten Sie unserer Diskussionsgruppe bei.
- Richten Sie Ihre Entwicklungsumgebung ein.
- Ordnen Sie jeden Ihrer Änderungssätze mit einem Problem (Fehlerbericht oder Funktionsanfrage) im GitHub-Issue Tracker zu. Falls noch keines vorhanden ist, erstellen Sie ein neues Problem und weisen Sie es sich selbst zu.
- Sehen Sie sich den Code an, erstellen Sie auf codereview.appspot.com ein neues Problem und schließen Sie die Codeüberprüfung ab. Im Folgenden finden Sie eine detaillierte Anleitung für alle diese Prozesse.
- Nachdem Ihr Code überprüft wurde und Sie die Genehmigung erhalten haben, können Sie den Code verwenden. Wenn Sie kein offizieller Contributor sind, lädt ein Contributor Ihr Änderungsset in das offizielle Repository.
Wir nutzen die folgenden Tools und Prozesse:
- Wir verwenden Git als Versionskontrollsystem.
- Wir verwenden Maven für das Build-System sowie ein binäres Distributionssystem.
- Wir verwenden codereview.appspot.com für Codeüberprüfungen. Beachten Sie jedoch, dass der Begriff "Problem" im Tool codereview.appspot.com für eine Anfrage zur Codeüberprüfung steht, während "Problem" im GitHub Issue Tracker eine Funktionsanfrage oder einen Fehlerbericht ist.
Wenn Sie ein Eclipse-Entwickler sind, verwenden Sie die im Verzeichnis .settings angegebene projektspezifische Codeformatierung, die automatisch von Eclipse verarbeitet wird.
Entwicklungsumgebung einrichten
Voraussetzungen
- Installieren Sie Java 6. Möglicherweise müssen Sie die Variable
JAVA_HOME
festlegen. - Installieren Sie Maven. In diesem Dokument wird davon ausgegangen, dass Sie mit Maven-Befehlen vertraut sind.
- Optional: Installieren Sie das Android SDK und legen Sie die Variable ANDROID_HOME auf den Installationspfad für Android fest.
- Installieren Sie Git.
Git einrichten
Verwenden Sie den Befehl git config
, um den standardmäßigen Anzeigenamen und die E-Mail-Adresse festzulegen:
git config --global user.name "YOUR NAME" git config --global user.email "YOUR EMAIL ADDRESS"
Über Git mit GitHub authentifizieren
Damit Sie den Code aus GitHub abrufen können, müssen Sie sich mit HTTP oder SSH bei GitHub authentifizieren. Bevor Sie mit der Anleitung unten fortfahren, lesen Sie die instructions zu den ersten Schritten mit dem Klonen von HTTPS oder SSH. Wenn Sie allgemein mehr über Git erfahren möchten, ist ProGit eine gute Ressource.
Code auschecken
HTTPS verwenden
Mit dem folgenden Befehl können Sie das Bibliotheks-Repository im Entwicklungs-Master-Zweig aufrufen:
git clone https://github.com/google/google-api-java-client.git
SSH verwenden
Wenn Sie das Bibliotheks-Repository im Entwicklungs-Master-Zweig ansehen möchten, benötigen Sie Schreibzugriff auf das GitHub-Repository. Führen Sie dann den folgenden Befehl aus:
git clone git@github.com:google/google-api-java-client.git
So wechseln Sie zu einem alternativen Zweig, z. B. 1.12:
git checkout --track origin/1.12
So wechseln Sie zurück zum Master-Branch:
git checkout master
So rufen Sie die neuesten Änderungen aus dem GitHub-Repository ab und aktualisieren den lokalen Arbeitsbaum auf den neuesten Commit:
git pull
Maven
Google Play-Dienste installieren
Wenn Sie das Projekt zum ersten Mal einrichten, müssen Sie die Datei google-play-services.jar installieren. Das geht so:
- Starten Sie Eclipse und wählen Sie Window > Android SDK Manager (Fenster > Android SDK Manager) aus oder führen Sie
android
in der Befehlszeile aus. - Scrollen Sie ans Ende der Paketliste und wählen Sie Extras > Google Play-Dienste aus.
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
Projekt kompilieren
mvn clean install
Maven installiert die kompilierten Binärprogramme in einem lokalen Repository (z. B. ~/.m2/repository). Sie sucht in diesem Repository nach Binärdateien, bevor sie aus dem Maven Central Repository abgerufen wird.
Hinweis:Diese Bibliothek hängt von google-http-java-client und google-oauth-java-client ab. Wenn Sie an einer neuen Version aller drei Bibliotheken arbeiten, die noch nicht für Maven Central freigegeben wurden, müssen Sie sie in der folgenden Reihenfolge kompilieren:
- google-http-java-client
- google-oauth-java-client
- google-api-java-client Durch die Kompilierung in dieser Reihenfolge wird sichergestellt, dass die kompilierten Binärprogramme von Maven für die Kompilierung der abhängigen Bibliothek abgerufen werden.
Ablauf der Codeüberprüfung
Upload.py-Skript herunterladen
Laden Sie das Skript upload.py herunter und fügen Sie es optional Ihrem PATH hinzu.
Wenn Sie upload.py
zum ersten Mal ausführen, werden Sie zur Eingabe eines anwendungsspezifischen Passworts aufgefordert:
Email (login for uploading to codereview.appspot.com): your_email_address@yourdomain.com Password for your_email_address@yourdomain.com:
Code wird zur Überprüfung vorbereitet
Bevor Sie den Code zur Überprüfung senden, müssen Sie Clirr ausführen, um Abwärtskompatibilitätsprobleme in Ihrem Code zu erkennen. Wenn Fehler gemeldet werden, müssen Sie diese entweder beheben oder die Datei „clirr-ignored-differences.xml“ aktualisieren.
mvn -q clirr:check
Sie müssen außerdem das FindBugs-Tool ausführen, um Programmfehler im Code zu erkennen. Werden Fehler gemeldet, müssen Sie diese entweder beheben oder die Datei „findbugs-exclusion.xml“ aktualisieren. FindBugs ist sehr langsam.
mvn findbugs:check
Sobald Ihre Änderung alle Tests bestanden hat, fügen Sie die Änderung dem Index hinzu (Git-Staging-Bereich):
git add .
Prüfen Sie noch einmal, ob alle hinzugefügten, geänderten oder gelöschten Dateien im Index vorhanden sind:
git status
Prüfen Sie in der Ausgabe von git status
den Abschnitt „Änderungen, für die ein Commit durchgeführt werden soll“.
Codeüberprüfung starten
Wenn Sie zur Überprüfung bereit sind, erstellen Sie ein neues Problem auf codereview.appspot.com:
upload.py --rev=HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...
Wenn Sie weitere Änderungen vorgenommen haben, stellen Sie die neuen Änderungen bereit. Führen Sie den folgenden Befehl aus, um einen neuen Patch hochzuladen, z. B. für die Ausgabenummer 123456:
upload.py --rev=HEAD -i 123456
Führen Sie upload.py --help
aus, um weitere Optionen zu erhalten.
Wenn Sie den typischen GitHub-Workflow bevorzugen, haben Sie wahrscheinlich das GitHub-Repository abgespalten und einen Zweig für diese neue Funktion oder Fehlerkorrektur erstellt. Wenn Sie Anfragen zur Codeüberprüfung von Ihrem eigenen Fork aus senden, achten Sie darauf, dass dieser mit dem Upstream-Repository synchron ist. Weitere Informationen finden Sie in der GitHub-Hilfe zum Synchronisieren einer Verzweigung.
Sie könnenupload.py auch für lokal durchgeführte Änderungssätze verwenden.
upload.py --rev=upstream/master:HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...
Codeprüfer
Wenn Sie ein Codeprüfer sind, importieren und testen Sie Änderungssätze, bevor Sie sie genehmigen, und führen Sie dann einen Commit durch und übertragen Sie die Änderungssätze in das Remote-Repository.
Änderungsset importieren
Damit Fehler frühzeitig erkannt werden, müssen Sie die neuesten Änderungen aus dem Remote-Repository in Ihre Arbeitsstruktur abrufen. Achten Sie darauf, dass der Arbeitsbaum sauber und der Index leer ist.
So rufen Sie die neuesten Commits aus dem Remote-Repository ab und führen sie zusammen:
git pull
So prüfen Sie, was sich in Ihrem Arbeitsbaum und Index befindet:
git status
So importieren Sie einen Patch in Ihren lokalen Git-Klon:
- Öffnen Sie das Problem in codereview.appspot.com.
- Suchen Sie für den betreffenden Patch oben rechts in der Patchspezifikation nach "Download raw" (Raw herunterladen).
- Klicken Sie auf „raw“, um eine URL für die zu importierende Datei abzurufen.
- Speichern Sie die RAW-Diff-Datei auf Ihrem lokalen Computer unter einem Namen wie „issue123456.diff“.
- Rufen Sie Ihre lokale Git-Arbeitsstruktur auf und wenden Sie den Unterschied mit dem Befehl
patch
an:
patch -p1 < issue123456.diff
Prüfen Sie, ob Sie den richtigen Unterschied importiert haben. Führen Sie dazu einen git diff
in Ihrer Arbeitsstruktur aus.
Änderungsset testen
Verwenden Sie den folgenden Befehl, um die Tests auszuführen und die Installation durchzuführen:
mvn clean install checkstyle:check
Änderungsset auf codereview.appspot.com genehmigen
Im Allgemeinen kann Code erst in das GitHub-Repository übertragen werden, wenn der Codeprüfer sich sicher ist, dass der Code bereit ist. An dieser Stelle ist es üblich, mit der Nachricht „LGTM“ (Looks Good To Me) zu antworten.
Commit des Codes durchführen
Wichtig: Bevor Sie einen Commit für Ihren Code durchführen, rufen Sie die neuesten Änderungen in Ihre Arbeitsstruktur ab und aktualisieren Sie diese auf den neuesten Commit aus dem GitHub-Repository:
git pull
Lösen Sie etwaige Konflikte und sorgen Sie dann dafür, dass alle Tests noch einmal bestanden werden.
So führen Sie einen lokalen Commit für den Code durch:
git commit
Gib eine Nachricht wie die folgende ein (vorausgesetzt, du behebst oder implementierst Problem 123, wie in der GitHub-Problemverfolgung aufgeführt):
#123: NullPointerException when passing null to processFoo() http://codereview.appspot.com/123456/
Vor dem ersten Doppelpunkt und der Beschreibung:
- Wenn dies die Fehlerbehebung für ein Problem auf dem Issue Tracker ist, geben Sie die Problemnummer wie gezeigt an.
- Wenn es sich um eine Änderung für eine bestimmte Zweigstelle handelt, geben Sie die Nummer der Zweigstelle an.
- Sie sind der
committer
dieses Commits, aber erwähnen Sie den Autor der Änderung, indem Sie ihn alsauthor
(--author=<author>
) kennzeichnen.
Geben Sie nach der Beschreibung immer einen Link zum Problem auf der Codeüberprüfungs-Website an. Dieser Link ist wichtig, da es ohne ihn keine bequeme Möglichkeit gibt, die mit einem Commit verknüpfte Codeüberprüfung herauszufinden. Dies ist nützlich, um den Verlauf der Diskussion zu verwalten.
So übertragen Sie die Änderung in das GitHub-Repository:
git push
Wenn Sie während git push
eine Fehlermeldung erhalten, dass Updates abgelehnt werden (möglicherweise haben Sie vergessen, git pull
auszuführen), gehen Sie so vor, um die neuesten Änderungen zusammenzuführen und Ihre Änderungen in das Remote-Repository zu übertragen:
git pull git commit git push
Problem wird geschlossen
Schließen Sie das Problem im Tool zur Codeüberprüfung. Das geht so:
- Wählen Sie das Problem in codereview.appspot.com aus.
- Klicken Sie oben links auf das „X“ vor „ID“.
Patches eines Changesets wiederherstellen
Wenn Sie aus irgendeinem Grund ein importiertes Changeset nicht mit Commit speichern möchten, löschen Sie es mit dem folgenden Befehl. Achtung: Dabei werden alle lokalen Änderungen gelöscht.
git checkout -- .