Come dare il proprio contributo

Contratti di licenza (Collaboratore)

Prima che possiamo accettare le tue patch del codice, devi inviare un singolo utente o un Contratto di licenza per i collaboratori (CLA):

  • Se sei una persona che scrive codice sorgente originale e sei sicuro di possedere la proprietà intellettuale, invia un CLA individuale.
  • Se lavori per un'azienda, la tua azienda deve inviare un CLA aziendale per indicare che hai il permesso di contribuire al tuo lavoro con questa libreria client.

Fai clic su uno dei due link qui sopra per accedere al CLA appropriato e alle istruzioni su come firmarlo e restituirlo. Una volta ricevuti, possiamo aggiungerti all'elenco ufficiale dei collaboratori.

Panoramica sull'invio delle patch

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

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

Utilizziamo i seguenti strumenti e processi:

  • Usiamo Git come nostro sistema di controllo della versione.
  • Utilizziamo Maven per il sistema di compilazione e un sistema di distribuzione binario.
  • Per le revisioni del codice, utilizziamo codereview.appspot.com. Tieni presente che nello strumento codereview.appspot.com il termine "issue&quot" indica una richiesta di revisione del codice, mentre in GitHub Issue Tracker viene indicato un "problema" una richiesta di funzionalità o una segnalazione di bug.

Se sei uno sviluppatore Eclipse, utilizza la formattazione del codice specifica del progetto specificata nella directory .settings che viene elaborata automaticamente da Eclipse.

Configurazione dell'ambiente di sviluppo

Prerequisiti

  1. Installa Java 6. Potresti dover impostare la variabile 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 in corso...

Utilizza il comando git config per impostare nome e 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 controllare il codice di GitHub, devi eseguire l'autenticazione con GitHub utilizzando HTTP o SSH. Prima di continuare con le istruzioni riportate di seguito, leggi le istruzioni di GitHub su come iniziare a utilizzare la clonazione HTTPS o SSH. Per saperne di più su Git in generale, la versione Pro Git è una buona risorsa.

Verifica del codice

Utilizzare HTTPS

Per verificare il repository della libreria nel ramo "master", esegui il seguente comando:

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

Utilizzo di SSH

Per verificare il repository della libreria nel ramo "master", assicurati di avere accesso in scrittura al repository GitHub, quindi esegui il comando seguente:

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 estrarre le ultime modifiche dal repository GitHub e aggiornare la tua struttura di lavoro locale all'ultimo commit:

git pull

Maven

Installa Google Play Services

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

  1. Avvia Eclipse e seleziona Window > Android SDK Manager o esegui android nella riga di comando.
  2. Scorri fino in fondo all'elenco dei pacchetti e seleziona Extras > Google Play Services.
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). Cerca i programmi binari nel repository prima di recuperarli 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 in Maven Central, devi compilarle nel seguente ordine:

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

Procedura di revisione del codice

Download dello script upload.py

Scarica lo script upload.py e, se vuoi, aggiungilo al tuo percorso.

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:

Preparare il codice per la revisione

Prima di inviare il codice per la revisione, devi eseguire Clirr per rilevare eventuali problemi di compatibilità con le versioni precedenti nel tuo codice. Se vengono segnalati errori, devi correggerli o aggiornare il file clirr-ignored-differences.xml.

mvn -q clirr:check

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

mvn findbugs:check

Dopo aver superato tutti i test, aggiungi la modifica all'indice (l'area temporanea di Git):

git add .

Verifica che tutti i file che hai aggiunto, modificato o eliminato si riflettano nell'indice:

git status

Nell'output di git status, controlla la sezione denominata "Modifiche da impegnare".

Avvio della revisione del codice

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 ulteriori modifiche, metti in scena le nuove modifiche. Per caricare una nuova patch, ad esempio per emettere il numero 123456, esegui il comando seguente: 

upload.py --rev=HEAD -i 123456

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

Se preferisci il tipico flusso di lavoro GitHub, probabilmente hai forzato il repository GitHub e creato un ramo per questa nuova funzionalità o correzione di bug. Quando invii richieste di revisione del codice dal tuo fork, assicurati che il fork sia sincronizzato con il repository a monte. Per ulteriori informazioni, consulta la guida di GitHub su come sincronizzare un fork.

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

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

Revisore codice

Se sei un revisore del codice, importa e verifica i set di modifiche prima di approvarli, quindi esegui il commit e il push dei set di modifiche nel repository remoto.

Importazione di un set di modifiche

Per rilevare gli errori in anticipo, assicurati di eseguire il pull delle ultime modifiche dal repository remoto nell'albero degli elementi di lavoro. Assicurati che l'albero di lavoro sia pulito e che l'indice sia vuoto.

Per estrarre e unire gli ultimi commit dal repository remoto:

git pull

Per controllare gli elementi dell'albero e dell'indice di lavoro:

git status

Per importare una patch nel clone Git locale:

  1. Apri il problema all'interno di codereview.appspot.com.
  2. Per la patch in questione, cerca "Scarica non elaborata" in alto a destra nella specifica della patch.
  3. Fai clic su "raw" per ottenere un URL per il file da importare.
  4. Salva il file diff non elaborato sulla tua macchina locale con un nome come issue123456.diff.
  5. Vai all'albero di lavoro Git locale e applica la differenza utilizzando il comando patch:
patch -p1 < issue123456.diff

Per verificare di avere importato la differenza corretta, esegui un git diff nel tuo albero di lavoro.

Test del set di modifiche in corso...

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

mvn clean install checkstyle:check

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

In generale, il codice non può essere trasferito al repository GitHub fino a quando il revisore del codice non verifica che il codice sia pronto. A quel punto, la convenzione è rispondere con il messaggio "LGTM".

Esegui il commit del codice

Importante: prima di eseguire il commit del codice, esegui il pull delle ultime modifiche nell'albero di lavoro e aggiorna l'albero di lavoro all'ultimo commit dal repository GitHub:

git pull

Eventuali conflitti possono essere risolti, quindi assicurati di superare tutti i test.

Per eseguire il commit del codice a livello locale: 

git commit

Inserisci un messaggio simile al seguente (supponendo che tu stia correggendo o implementando il problema n. 123, come elencato in Issue Tracker di GitHub):

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

Prima dei due punti e della descrizione:

  • Se si tratta di una risoluzione di un problema su Issue Tracker, includi il numero di problema, come mostrato.
  • Se si tratta di una modifica per un determinato ramo, includi il numero del ramo.
  • Sarai il committer di questo commit, ma dai il tuo credito all'autore della modifica contrassegnandolo come author (--author=<author>).

Dopo la descrizione, includi sempre un link al problema sul sito di codereview. Questo link è importante perché senza di esso non c'è un modo pratico per comprendere la revisione del codice associata a un commit, utile per mantenere una cronologia della discussione.

Per eseguire il push della modifica al repository GitHub:

git push

Se in git push ricevi un messaggio di errore relativo agli aggiornamenti rifiutati (forse hai dimenticato di eseguire git pull), ecco come eseguire l'unione con le ultime modifiche ed eseguire il push delle modifiche al repository remoto: 

git pull
git commit
git push

Chiudere il problema

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

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

Annullamento dell'applicazione di un set di modifiche

Se per qualche motivo decidi di non eseguire il commit di un set di modifiche che hai importato, utilizza il comando seguente per eliminarlo. Fai attenzione: cancella letteralmente tutte le modifiche locali. 

git checkout -- .