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:
- Unterzeichnen Sie wie oben beschrieben eine Contributor-Lizenzvereinbarung.
- Treten Sie unserer Diskussionsgruppe bei.
- Richten Sie Ihre Entwicklungsumgebung ein.
- 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.
- 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.
- 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
- 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 Ihre ANDROID_HOME-Variable auf den Installationspfad für Android fest.
- 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:
- Starten Sie Eclipse und wählen Sie Window > Android SDK Manager aus oder führen Sie
android
in der Befehlszeile aus. - 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:
- google-http-java-client
- google-oauth-java-client
- 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:
- Öffnen Sie das Problem in codereview.appspot.com.
- Suchen Sie für den betreffenden Patch rechts oben in der Patchspezifikation nach „Raw-Download“.
- Klicken Sie auf „Roh“, um eine URL für die zu importierende Datei zu erhalten.
- Speichern Sie die Raw-Diff-Datei auf Ihrem lokalen Computer mit einem Namen wie „issue123456.diff“.
- 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 alsauthor
(--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:
- Wählen Sie das Problem in codereview.appspot.com aus.
- 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 -- .