So kannst du Fragen beantworten

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Contributor-Lizenzvereinbarungen (CLAs)

Bevor wir Ihre Code-Patches akzeptieren können, müssen Sie entweder eine Einzel- oder eine Corporate Contributor-Lizenzvereinbarung (CLA) einreichen:

  • Wenn Sie eine Person sind, die ursprünglichen Quellcode schreibt, und sicher sind, dass Sie Inhaber des geistigen Eigentums sind, reichen Sie eine individuelle CLA ein.
  • Wenn Sie für ein Unternehmen arbeiten, müssen Sie eine Unternehmens-CLA einreichen, um anzugeben, dass Sie Ihre Arbeit in diese Clientbibliothek aufnehmen 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 der offiziellen Liste der Mitwirkenden hinzufügen.

Patches einreichen – Übersicht

Wenn Sie Code für dieses Projekt beitragen möchten, gehen Sie so vor:

  1. Unterzeichnen Sie wie oben beschrieben eine Contributor-Lizenzvereinbarung.
  2. Treten Sie unserer Diskussionsgruppe bei.
  3. Richten Sie Ihre Entwicklungsumgebung ein.
  4. Verknüpfen Sie jeden Ihrer Änderungssätze mit einem Problem (Fehlerbericht oder Funktionsanfrage) in unserer GitHub-Problemverfolgung. Erstellen Sie ein neues Problem, wenn es noch keins gibt, und weisen Sie es sich selbst zu.
  5. Lesen Sie den Code, erstellen Sie auf codereview.appspot.com ein neues Problem und schließen Sie die Codeüberprüfung ab. Eine ausführliche Anleitung für alle diese Prozesse finden Sie unten.
  6. Nachdem der Code überprüft wurde und Sie die Genehmigung erhalten, führen Sie den Code aus. Wenn Sie kein offizieller Beitragender sind, wird Ihr Änderungssatz durch einen Beitragenden in das offizielle Repository übertragen.

Wir nutzen die folgenden Tools und Prozesse:

  • Wir verwenden Git als Versionsverwaltungssystem.
  • Wir verwenden Maven für das Build-System und ein binäres Distributionssystem.
  • Für Codeüberprüfungen verwenden wir codereview.appspot.com. Beachten Sie jedoch, dass im Tool codereview.appspot.com der Begriff "issue" eine Anfrage zur Codeüberprüfung bedeutet, in der Problemverfolgung von GitHub hingegen eine Funktionsanfrage oder ein Fehlerbericht.

Wenn Sie ein Eclipse-Entwickler sind, verwenden Sie die projektspezifische Codeformatierung, die im Verzeichnis ".settings" angegeben ist, das 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 Ihre ANDROID_HOME-Variable auf den Installationspfad für Android fest.
  4. Installieren Sie Git.

Git einrichten

Verwenden Sie den Befehl git config, um Ihren Standardanzeigenamen und Ihre E-Mail-Adresse festzulegen:

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

Mit Git aus GitHub authentifizieren

Damit Sie den Code von GitHub abrufen können, müssen Sie sich über HTTP oder SSH bei GitHub authentifizieren. Bevor Sie mit der Anleitung unten fortfahren, lesen Sie die GitHub-Anleitung zu den ersten Schritten mit HTTPS oder dem Klonen von SSH. Wenn Sie mehr über Git im Allgemeinen erfahren möchten, ist Pro Git eine gute Ressource.

Code wird geprüft

HTTPS verwenden

Führen Sie den folgenden Befehl aus, um sich das Bibliotheks-Repository im Entwicklungszweig anzusehen:

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

SSH verwenden

Prüfen Sie, ob Sie Schreibzugriff auf das GitHub-Repository haben, und prüfen Sie dann das Bibliotheks-Repository im Entwicklungszweig &master und führen Sie 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-Zweig:

git checkout master

So rufen Sie die neuesten Änderungen aus dem GitHub-Repository ab und aktualisieren Ihre lokale Arbeitsstruktur 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 aus oder führen Sie android in der Befehlszeile aus.
  2. Scrollen Sie zum 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). Es wird nach Binärdateien in diesem Repository gesucht, bevor es 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 in Maven Central veröffentlicht 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 Zusammenstellung dieser Reihenfolge wird sichergestellt, dass Maven die kompilierten Binärprogramme für die Kompilierung der abhängigen Bibliothek abruft.

Ablauf der Codeüberprüfung

Skript „upload.py“ herunterladen

Laden Sie das Skript upload.py herunter und fügen Sie es Ihrem PATH hinzu.

Wenn Sie upload.py zum ersten Mal ausführen, werden Sie nach einem anwendungsspezifischen Passwort gefragt:

Email (login for uploading to codereview.appspot.com): your_email_address@yourdomain.com
Password for your_email_address@yourdomain.com:

Code zur Überprüfung vorbereiten

Bevor Sie den Code zur Überprüfung senden, müssen Sie Clirr ausführen, um abwärtskompatible Probleme in Ihrem Code zu erkennen. Wenn Fehler gemeldet werden, müssen Sie diese entweder beheben oder die Datei clirr-ignored-unterschieds.xml aktualisieren.

mvn -q clirr:check

Außerdem müssen Sie das FindBugs-Tool ausführen, um Fehler im Code zu erkennen. Wenn Fehler gemeldet werden, müssen Sie diese entweder korrigieren oder die Datei „findbugs-exclude.xml“ aktualisieren. Hinweis: FindBugs ist sehr langsam.

mvn findbugs:check

Nachdem Ihre Änderung alle Tests bestanden hat, fügen Sie sie dem Index (dem Git-Staging-Bereich) hinzu:

git add .

Prüfe, ob alle Dateien, die du hinzugefügt, geändert oder gelöscht hast, im Index angezeigt werden:

git status

Prüfen Sie in der Ausgabe von git status den Abschnitt "Änderungen mit Commit."

Codeüberprüfung starten

Erstellen Sie zur Überprüfung 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 ...

Nachdem Sie weitere Änderungen vorgenommen haben, stellen Sie sie bereit. Führen Sie den folgenden Befehl aus, um einen neuen Patch hochzuladen, beispielsweise 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 verzweigt und einen Zweig für diese neue Funktion oder Fehlerkorrektur erstellt. Wenn Sie Codeüberprüfungsanfragen von Ihrer eigenen Verzweigung aus senden, muss Ihre Verzweigung mit dem Upstream-Repository synchronisiert sein. Weitere Informationen finden Sie in der GitHub-Hilfe unter Fork synchronisieren.

Sie können sie auch für lokal festgeschriebene Ä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. Speichern Sie dann die Änderungssätze und übertragen Sie sie per Push in das Remote-Repository.

Änderungssätze importieren

Achten Sie darauf, die neuesten Änderungen aus dem Remote-Repository in Ihre Arbeitsstruktur zu übertragen, um Fehler frühzeitig zu erkennen. Achten Sie darauf, dass Ihre Arbeitsstruktur sauber ist und Ihr Index leer ist.

So rufen Sie aktuelle Commits aus dem Remote-Repository ab und führen diese zusammen:

git pull

So prüfen Sie, was in Ihrer Arbeitsstruktur und Ihrem Index funktioniert:

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 rechts oben in der Patchspezifikation nach „Raw-Download“.
  3. Klicken Sie auf „Roh“, um eine URL für die zu importierende Datei zu erhalten.
  4. Speichern Sie die Raw-Diff-Datei auf Ihrem lokalen Computer mit einem Namen wie „issue123456.diff“.
  5. Wechseln Sie zu Ihrem lokalen Git-Arbeitsbaum und wenden Sie den Unterschied mit dem Befehl patch an:
patch -p1 < issue123456.diff

Führen Sie einen git diff in Ihrer Arbeitsstruktur aus, um zu prüfen, ob Sie den richtigen Unterschied importiert haben.

Änderungssatz testen

Führen Sie den folgenden Befehl aus, um die Tests auszuführen und die Installation auszuführen:

mvn clean install checkstyle:check

Änderungssatz auf codereview.appspot.com genehmigen

Im Allgemeinen kann Code erst in das GitHub-Repository übertragen werden, wenn der Codeprüfer sicher ist, dass er bereit ist. Die Konvention ist dann, mit der Nachricht „LGTM“ zu antworten (das sieht gut aus).

Code per Commit übertragen

Wichtig: Bevor Sie den Code per Commit übertragen, laden Sie die neuesten Änderungen in die Arbeitsstruktur herunter und aktualisieren Sie diese aus dem GitHub-Repository auf den neuesten Commit:

git pull

Wenn es Konflikte gibt, beheben Sie diese. Achten Sie darauf, dass alle Tests wieder bestanden werden.

So führen Sie den Code lokal durch: 

git commit

Geben Sie eine Nachricht wie die folgende ein, sofern Sie das Problem 123 beheben oder implementieren, 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 ein Problem in der Problemverfolgung ist, geben Sie die Problemnummer wie unten gezeigt an.
  • Wenn sich dies auf eine bestimmte Zweigstelle bezieht, geben Sie die Filialnummer an.
  • Sie sind die committer dieses Commits, aber belohnen Sie den Autor der Änderung, indem Sie ihn als author (--author=<author>) markieren.

Gib nach der Beschreibung immer einen Link zum Problem auf der Codeüberprüfungswebsite an. Dieser Link ist wichtig, da es ohne diesen Code keine praktische Möglichkeit bietet, die mit einem Commit verknüpfte Codeüberprüfung zu ermitteln. Diese Methode ist nützlich, um einen Verlauf der Diskussion zu führen.

So übertragen Sie die Änderung an das GitHub-Repository:

git push

Wenn während git push eine Fehlermeldung angezeigt wird, dass Updates abgelehnt werden (und vielleicht vergessen haben, git pull auszuführen), gehen Sie so vor, um die Änderungen mit den neuesten Änderungen zusammenzuführen und die Änderungen an das Remote-Repository zu übertragen:

git pull
git commit
git push

Problem wird geschlossen

Schließen Sie das Problem im Tool für die Codeüberprüfung. Das geht so:

  1. Wählen Sie das Problem in codereview.appspot.com aus.
  2. Klicken Sie auf das „X“ links oben, das vorangegangene „&“.

Patchset wird gepatcht

Wenn Sie einen importierten Importsatz aus irgendeinem Grund nicht mit einem Commit verknüpfen möchten, können Sie ihn mit dem folgenden Befehl entfernen. Achtung: Dadurch werden alle lokalen Änderungen gelöscht. 

git checkout -- .