Come dare il proprio contributo

Contratti di licenza per collaboratori (CLA)

Prima di poter accettare le tue patch di codice, devi inviare un Contratto di licenza per collaboratori (CLA) individuale o aziendale:

• Se sei una persona che scrive codice sorgente originale e non hai la certezza di possedere la proprietà intellettuale, invia un Contratto di licenza con l'utente finale (CLA) individuale.
• Se lavori per un'azienda, quest'ultima deve inviare un Contratto di licenza con l'utente finale (CLA) per indicare che hai l'autorizzazione a contribuire con il tuo lavoro a questa libreria cliente.

Segui uno dei due link precedenti per accedere al Contratto di licenza per i contenuti appropriato e alle istruzioni su come firmarlo e restituirlo. Una volta ricevuta la richiesta, potremo aggiungerti all'elenco ufficiale dei collaboratori.

Panoramica dell'invio delle patch

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

1. Firma un Contratto di licenza di collaboratore, come descritto sopra.
2. Partecipa al nostro gruppo di discussione.
3. Configura il tuo ambiente di sviluppo.
4. Associa ogni 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 sono riportate istruzioni dettagliate per tutte queste procedure.
6. Dopo aver esaminato il codice e aver ricevuto l'approvazione, esegui il commit del codice. Se non sei un collaboratore ufficiale, un collaboratore inserisce il tuo set di modifiche nel repository ufficiale.

Utilizziamo i seguenti strumenti e procedure:

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

Se sei uno sviluppatore di 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. Potrebbe essere necessario impostare la variabile JAVA_HOME.
2. Installa Maven. In questo documento si presume 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

Utilizza 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 recuperare il codice da GitHub, devi essere autenticato con GitHub utilizzando HTTP o SSH. Prima di continuare con le istruzioni riportate di seguito, leggi le instructions di GitHub su come iniziare a utilizzare la clonazione HTTPS o SSH. Per saperne di più su Git in generale, Pro Git è un'ottima risorsa.

Verifica del codice

Utilizzo di HTTPS

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

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

Utilizzo di SSH

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

git clone [e-mail]: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 principale:

git checkout master

Per eseguire il pull delle ultime modifiche dal repository GitHub e aggiornare l'albero 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 Finestra > Android SDK Manager oppure esegui android dalla riga di comando.
2. Scorri fino alla fine dell'elenco dei pacchetti e seleziona Extra > 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 su una nuova versione di tutte e tre le librerie non ancora rilasciate in Maven Central, devi compilarle 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 utilizzi 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, facoltativamente, aggiungilo al tuo PERCORSO.

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

Email (login for uploading to codereview.appspot.com): [e-mail]
Password for [e-mail]: 

Preparazione del codice per la revisione

Prima di inviare il codice per la revisione, devi eseguire Clirr per individuare i problemi di compatibilità con le versioni precedenti del 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 eventuali bug nel codice. Se vengono segnalati degli errori, devi correggerli o aggiornare il file findbugs-exclude.xml. Tieni presente che FindBugs è molto lento.

mvn findbugs:check

Una volta che la modifica supera tutti i test, aggiungi la modifica all'indice (l'area temporanea Git):

git add .

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

git status

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

Inizio 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 ...

Suggerimento: se vuoi che il problema sia visibile ai revisori e a quelli inclusi solo nella riga Cc, utilizza l'opzione --private.

Dopo aver apportato altre modifiche, applica in modo temporaneo le modifiche. Per caricare una nuova patch, ad esempio per il numero 123456, esegui questo comando:

upload.py --rev=HEAD -i 123456

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

Se preferisci il tipico flusso di lavoro di GitHub, probabilmente hai eseguito il fork del repository di 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 sia sincronizzato con il repository upstream. Per maggiori informazioni, consulta la guida GitHub su come sincronizzare una fork.

Puoi utilizzare upload.py anche per i set di modifiche confermati 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 dei set di modifiche ed eseguine il push nel repository remoto.

Importazione di un set di modifiche

Per individuare tempestivamente gli errori, assicurati di eseguire il pull delle modifiche più recenti dal repository remoto nell'albero di lavoro. assicurati che l'albero di lavoro sia pulito e che l'indice sia vuoto.

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

git pull

Per verificare il contenuto dell'albero e dell'indice di lavoro:

git status

Per importare una patch nel tuo clone di Git locale:

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

patch -p1 < issue123456.diff

Per verificare di aver importato le differenze corrette, esegui un comando git diff nell'albero di lavoro.

Test dell'insieme di modifiche

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

mvn clean install checkstyle:check

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

In generale, non è possibile eseguire il push del codice al repository GitHub finché il revisore del codice non verifica che il codice sia pronto. A quel punto, la convenzione è quella di rispondere con il messaggio "LGTM" (Looks Good To Me).

Esecuzione del 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

In caso di conflitti, risolvili, quindi assicurati che tutti i test vengano superati di nuovo.

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 indicato nell'Issue Tracker su GitHub):

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

Prima dei primi due punti e della descrizione:

• Se il problema persiste nel Tracker dei problemi, includi il numero del problema, come mostrato.
• Se si tratta di una modifica per un ramo specifico, includi il numero della filiale.
• Sarai il committer di questo impegno, ma ringrazia l'autore della modifica contrassegnandolo come author (--author=<author>).

Seguendo la descrizione, includi sempre un link al problema sul sito di revisione del codice. Questo link è importante perché senza di esso non c'è un modo conveniente per comprendere la revisione del codice associata a un commit, il che è 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 (forse hai dimenticato di eseguire git pull), ecco come eseguire l'unione con le modifiche più recenti ed eseguirne il push al repository remoto:

git pull
git commit
git push

Chiusura del 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" in alto a sinistra, che precede "ID".

Annullamento dell'applicazione dell'applicazione di un set di modifiche

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

git checkout -- .