Come dare il proprio contributo

Contratti di licenza dei collaboratori (CLA)

Prima di poter accettare le patch del codice, devi inviare una richiesta o un Contratto di licenza per collaboratori (CLA):

  • Se sei una persona che scrive il codice sorgente originale e hai la certezza che possiedi la proprietà intellettuale, invia una CLA singola.
  • Se lavori per un'azienda, quest'ultima deve inviare un CLA aziendale. per indicare che puoi contribuire con il tuo lavoro a questa libreria client.

Segui uno dei due link precedenti per accedere al CLA e istruzioni su come firmarlo e restituirlo. Una volta ricevuto, ti aggiungeremo all'elenco ufficiale dei collaboratori.

Panoramica dell'invio delle patch

Per contribuire con codice a questo progetto, segui questi passaggi generali:

  1. Firma un Contratto di licenza per collaboratori, come descritto sopra.
  2. Partecipa al nostro gruppo di discussione.
  3. Configura l'ambiente di sviluppo.
  4. Associa ogni set di modifiche a un problema (una segnalazione di bug o una funzione richiesta) nel nostro Issue Tracker GitHub. Crea un nuovo problema (se non ne esiste già uno) e assegnalo a te stesso.
  5. Verifica il codice, crea un nuovo problema su codereview.appspot.com e completa la procedura di revisione del codice. Di seguito sono riportate istruzioni dettagliate per tutti questi processi.
  6. Dopo aver esaminato il codice e ricevuto l'approvazione, esegui il commit del codice. Se non sei un collaboratore ufficiale, quest'ultimo estrae il tuo insieme di modifiche nel repository ufficiale.

Utilizziamo i seguenti strumenti e processi:

  • Utilizziamo Git come sistema di controllo della versione.
  • Utilizziamo Maven per il sistema di compilazione, un sistema di distribuzione binario.
  • Utilizziamo codereview.appspot.com per il codice le recensioni. (Tuttavia, tieni presente che nello strumento codereview.appspot.com, il termine "problema" indica una richiesta di revisione del codice, mentre in GitHub Issue Tracker viene indicato un "problema" è un una richiesta di funzionalità o una segnalazione di bug).

Se sei uno sviluppatore di Eclipse, usa la formattazione del codice specifica del progetto specificato nella directory .settings, elaborato automaticamente da Eclipse.

Configurazione dell'ambiente di sviluppo

Prerequisiti

  1. Installa Java 6. Potresti dover impostare JAVA_HOME .
  2. Installa Maven. (Questo documento presuppone che tu abbia una conoscenza di base dei comandi Maven).
  3. (Facoltativo) Installa l'SDK Android e imposta la variabile ANDROID_HOME sul percorso di installazione per Android.
  4. Installa Git.

Configurazione di Git

Usa il comando git config per impostare il nome visualizzato e l'indirizzo email predefiniti:

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

Autenticazione con GitHub da Git

Per poter estrarre il codice da GitHub, devi aver eseguito l'autenticazione con su GitHub utilizzando HTTP o SSH. Prima di continuare con istruzioni riportate di seguito, leggi il documento istruzioni su come ottenere è iniziato con la clonazione HTTPS o SSH. Se vuoi saperne di più su Git in in generale, Pro Git è una buona risorsa.

Controllo del codice in corso...

Utilizzo di HTTPS

Per controllare il repository della libreria nel "master" di sviluppo ramo esegui questo comando:

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

Utilizzo di SSH

Per controllare il repository della libreria nel "master" di sviluppo ramo, creare assicurati di avere accesso in scrittura al repository GitHub, quindi esegui questo comando:

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

Per passare a un ramo alternativo, ad esempio 1.12:

git checkout --track origin/1.12

Per tornare al ramo master:

git checkout master

Per eseguire il pull delle modifiche più recenti dal repository GitHub e aggiornare il tuo locale di lavoro all'ultimo commit:

git pull

Maven

Installa Google Play Services

La prima volta che configuri il progetto, devi installare google-play-services.jar. Per:

  1. Avvia Eclipse e seleziona Finestra > Android SDK Manager oppure esegui android nella riga di comando.
  2. Scorri fino alla fine dell'elenco di pacchetti e seleziona Extra > Google Play Google Cloud.
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

Compila il progetto

mvn clean install

Maven installa i programmi binari compilati in un repository locale (ad esempio ~/.m2/repository). Prima del recupero, cerca i file binari nel repository. dal repository centrale Maven.

Nota: Questa libreria dipende da google-http-java-client e google-oauth-java-client. Quando lavori a una nuova versione di tutte e tre le librerie non ancora rilasciate a Maven Central, devi compilarli nel seguente ordine:

  1. google-http-java-client
  2. google-oauth-java-client
  3. google-api-java-client La compilazione in questo ordine garantisce che Maven rilevi i file binari compilati per la compilazione della libreria dipendente.

Procedura di revisione del codice

Scaricare lo script upload.py

Scarica lo script upload.py e, se vuoi, aggiungerlo al tuo PATH.

La prima volta che esegui upload.py, ti viene chiesta una password specifica per l'applicazione:

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

Preparazione del codice per la revisione

Prima di inviare il codice per la revisione, devi eseguire Clirr per recuperarlo a ritroso problemi di compatibilità nel tuo codice. Se vengono segnalati errori, devi correggili o aggiorna il file clirr-ignored-differences.xml.

mvn -q clirr:check

Devi anche eseguire lo strumento FindBugs per individuare i bug nel codice. Eventuali errori vengono segnalati, devi correggerli o aggiornare il file searchbugs-excluded.xml . Tieni presente che FindBugs è molto lento.

mvn findbugs:check

Una volta che la modifica ha superato tutti i test, aggiungila all'indice (la gestione temporanea Git area):

git add .

Verifica che tutti i file che hai aggiunto, modificato o eliminato siano riportati nell'indice:

git status

Nell'output git status, controlla la sezione "Modifiche di cui eseguire il commit".

Avvio della revisione del codice in corso...

Quando tutto è pronto per la revisione, crea un nuovo problema su codereview.appspot.com: 

upload.py --rev=HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...

Dopo aver apportato altre modifiche, procedi in un'area intermedia. Per caricare una nuova patch, ad esempio per emettere il numero 123456, esegui questo comando: 

upload.py --rev=HEAD -i 123456

Per ulteriori opzioni, esegui upload.py --help.

Se preferisci il tipico GitHub flusso di lavoro, probabilmente hai eseguito il fork GitHub di ASL e di aver creato un ramo per questa nuova funzionalità o correzione di bug. Quando invia codice rivedi le richieste dalla tua fork, assicurati che quest'ultima sia sincronizzata con il repository upstream. Per maggiori informazioni, consulta la guida di GitHub su come sincronizzare un fork.

Puoi utilizzare upload.py anche per i set di modifiche eseguiti localmente.

upload.py --rev=upstream/master:HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...

Revisore di codice

Se sei un revisore di codice, importa e testa i set di modifiche prima di approvarli, eseguire il commit ed eseguire il push dei set di modifiche al repository remoto.

Importazione di un set di modifiche

Per individuare gli errori in anticipo, assicurati di eseguire il pull delle ultime modifiche dal telecomando repository Git nel tuo albero di lavoro. Assicurati che l'albero funzionante sia pulito l'indice è vuoto.

Per eseguire il pull e l'unione dei commit più recenti dal repository remoto:

git pull

Per verificare cosa c'è nell'albero e nell'indice di lavoro:

git status

Per importare una patch nel tuo clone Git locale:

  1. Apri il problema all'interno di codereview.appspot.com.
  2. Per la patch in questione, cerca "Download raw" (Download non elaborato). in alto a destra nella le specifiche della patch.
  3. Fai clic su "Raw" per ottenere un URL per l'importazione del file.
  4. Salva il file diff non elaborato sulla tua macchina locale con un nome come problema123456.diff.
  5. Vai all'albero di lavoro Git locale e applica la differenza utilizzando patch :
patch -p1 < issue123456.diff

Per verificare di aver importato il confronto corretto, esegui un git diff nel tuo albero funzionante.

Test del set di modifiche

Per eseguire i test e installare, utilizza il seguente comando:

mvn clean install checkstyle:check

Approvazione di un set di modifiche su codereview.appspot.com

In generale, il codice non può essere sottoposto a push nel repository GitHub fino a quando il revisore del codice non può che il codice sia pronto. A quel punto, la convenzione è rispondere con il messaggio "Tutto a posto" (Mi sembra buona).

Esegui il commit del codice

Importante: prima di eseguire il commit del codice, esegui il pull delle ultime modifiche e aggiornalo all'ultimo commit da GitHub repository:

git pull

In caso di conflitti, risolvili e poi assicurati di eseguire tutti i test passare di nuovo.

Per eseguire il commit del codice locally: 

git commit

Inserisci un messaggio come il seguente (supponendo che tu stia correggendo o implementando) Numero 123, come elencato su GitHub Monitoraggio problemi):

#123: NullPointerException when passing null to processFoo()
http://codereview.appspot.com/123456/

Prima dei primi due punti e della descrizione:

  • Se questa è una soluzione a un problema in Issue Tracker, includi il numero del problema, come mostrato.
  • Se si tratta di una modifica per un ramo particolare, includi il numero della filiale.
  • Sarai il committer di questo impegno, ma menziona il l'autore della modifica contrassegnandolo come author (--author=<author>).

Dopo la descrizione, includi sempre un link al problema nella revisione del codice. sito. Questo link è importante perché, senza il link, non esiste un modo comodo per la revisione del codice associata a un commit, utile per mantenere una cronologia della discussione.

Per eseguire il push della modifica nel repository GitHub:

git push

Se durante il periodo git push ricevi un messaggio di errore relativo al rifiuto degli aggiornamenti (ad esempio, hai dimenticato di eseguire git pull), ecco come eseguire l'unione alle ultime modifiche esegui il push delle modifiche nel repository remoto: 

git pull
git commit
git push

Chiusura del problema

Assicurati di chiudere il problema nello strumento di revisione del codice. Per:

  1. Seleziona il problema in codereview.appspot.com.
  2. Fai clic sulla "X" in alto a sinistra, prima di "Id".

Annullamento delle patch di un set di modifiche

Se per qualche motivo decidi di non eseguire il commit di un set di modifiche importato, utilizza seguente per eliminarlo. Attenzione: tutte le modifiche locali vengono cancellate letteralmente. 

git checkout -- .