So kannst du Fragen beantworten

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:

  1. Unterzeichnen Sie wie oben beschrieben eine Mitwirkende-Lizenzvereinbarung.
  2. Treten Sie unserer Diskussionsgruppe bei.
  3. Richten Sie Ihre Entwicklungsumgebung ein.
  4. 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.
  5. 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.
  6. 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

  1. Installieren Sie Java 6. Möglicherweise müssen Sie die Variable JAVA_HOME festlegen.
  2. Installieren Sie Maven. In diesem Dokument wird davon ausgegangen, dass Sie mit Maven-Befehlen vertraut sind.
  3. Optional: Installieren Sie das Android SDK und legen Sie die Variable ANDROID_HOME auf den Installationspfad für Android fest.
  4. 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:

  1. 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.
  2. 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:

  1. google-http-java-client
  2. google-oauth-java-client
  3. 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:

  1. Öffnen Sie das Problem in codereview.appspot.com.
  2. Suchen Sie für den betreffenden Patch oben rechts in der Patchspezifikation nach "Download raw" (Raw herunterladen).
  3. Klicken Sie auf „raw“, um eine URL für die zu importierende Datei abzurufen.
  4. Speichern Sie die RAW-Diff-Datei auf Ihrem lokalen Computer unter einem Namen wie „issue123456.diff“.
  5. 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 als author (--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:

  1. Wählen Sie das Problem in codereview.appspot.com aus.
  2. 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 -- .