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:
- Firma un Contratto di licenza per collaboratori, come descritto sopra.
- Partecipa al nostro gruppo di discussione.
- Configura l'ambiente di sviluppo.
- 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.
- 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.
- 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
- Installa Java 6. Potresti dover impostare
JAVA_HOME
. - Installa Maven. (Questo documento presuppone che tu abbia una conoscenza di base dei comandi Maven).
- (Facoltativo) Installa l'SDK Android e imposta la variabile ANDROID_HOME sul percorso di installazione per Android.
- 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:
- Avvia Eclipse e seleziona Finestra > Android SDK Manager oppure esegui
android
nella riga di comando. - 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:
- google-http-java-client
- google-oauth-java-client
- 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:
- Apri il problema all'interno di codereview.appspot.com.
- Per la patch in questione, cerca "Download raw" (Download non elaborato). in alto a destra nella le specifiche della patch.
- Fai clic su "Raw" per ottenere un URL per l'importazione del file.
- Salva il file diff non elaborato sulla tua macchina locale con un nome come problema123456.diff.
- 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 comeauthor
(--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:
- Seleziona il problema in codereview.appspot.com.
- 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 -- .