Comment contribuer

Contrats de licence pour les contributeurs

Pour que nous puissions accepter vos correctifs de code, vous devez nous envoyer ou un contrat de licence pour les contributeurs (CLC) d'entreprise :

  • Si vous écrivez du code source original et que vous êtes que vous détenez les droits de propriété intellectuelle, envoyez une CLC individuel.
  • Si vous travaillez pour une entreprise, celle-ci doit envoyer un CLC. pour indiquer que vous êtes autorisé à contribuer à cette bibliothèque cliente.

Cliquez sur l'un des deux liens ci-dessus pour accéder au CLA approprié et aux instructions expliquant comment signer et renvoyer le contrat. Dès réception, nous pourrons vous ajouter à la liste officielle des contributeurs.

Présentation de l'envoi de correctifs

Pour contribuer au code de ce projet, procédez comme suit:

  1. Signez un contrat de licence Contributeur, tel que décrit ci-dessus.
  2. Rejoignez notre groupe de discussion.
  3. Configurez votre environnement de développement.
  4. Associez chacun de vos ensembles de modifications à un problème (rapport de bug ou fonctionnalité). ) dans l'outil GitHub Issue Tracker. Créez un problème, s'il n'en existe pas déjà, et attribuez-le à vous-même.
  5. Vérifiez le code, créez un problème sur codereview.appspot.com et terminez le processus de revue de code. Vous trouverez ci-dessous des instructions détaillées concernant l'ensemble de ces processus.
  6. Une fois que votre code a été examiné et que vous avez reçu l'approbation, validez-le. Si vous n'êtes pas un contributeur officiel, un contributeur extrait votre ensemble de modifications dans le référentiel officiel.

Nous utilisons les outils et processus suivants:

  • Nous utilisons Git comme système de contrôle des versions.
  • Nous utilisons Maven pour le système de compilation, ainsi que un système de distribution binaire.
  • Nous utilisons codereview.appspot.com pour le code avis. Notez toutefois que dans l'outil codereview.appspot.com, le terme "problème" signifie une demande de révision de code, alors que dans GitHub Issue Tracker, un "problème" est un demande de fonctionnalité ou rapport de bug).

Si vous êtes un développeur Eclipse, utilisez la mise en forme de code spécifique au projet. spécifié dans le répertoire .settings automatiquement traité par Eclipse.

Configurer l'environnement de développement

Prérequis

  1. Installez Java 6. Vous devrez peut-être configurer votre JAVA_HOME .
  2. Installez Maven. (Ce document suppose que vous avez des connaissances de base sur les commandes Maven.)
  3. Facultatif: Installer le SDK Android et définissez votre variable ANDROID_HOME sur l'emplacement d'installation d'Android.
  4. Installez Git.

Configurer Git

Utilisez la commande git config pour définir le nom à afficher et l'adresse e-mail par défaut:

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

S'authentifier avec GitHub à partir de Git

Pour pouvoir extraire le code de GitHub, vous devez vous authentifier avec GitHub via HTTP ou SSH. Avant de passer aux les instructions ci-dessous, consultez la documentation instructions pour savoir comment a commencé par un clonage HTTPS ou SSH. Si vous souhaitez en savoir plus sur Git dans Pro Git est une bonne ressource.

Vérifier le code

Utiliser HTTPS

Pour consulter le dépôt de la bibliothèque dans le "maître" de développement, procédez comme suit : branche, exécutez la commande suivante:

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

Utiliser SSH

Pour consulter le dépôt de la bibliothèque dans le "maître" de développement, procédez comme suit : branche, créer bien sûr que disposer d'un accès en écriture au dépôt GitHub, exécutez la commande suivante:

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

Pour basculer vers une autre branche, par exemple 1.12, procédez comme suit:

git checkout --track origin/1.12

Pour revenir à la branche principale, procédez comme suit:

git checkout master

Pour récupérer les dernières modifications à partir du dépôt GitHub et mettre à jour votre fichier local au dernier commit:

git pull

Maven

Installer les services Google Play

La première fois que vous configurez le projet, vous devez installer "google-play-services.jar". Pour ce faire :

  1. Lancez Eclipse et sélectionnez Window > Android SDK Manager ou exécutez android au niveau de la ligne de commande.
  2. Faites défiler la liste des packages jusqu'en bas, puis sélectionnez Bonus > 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

Compiler le projet

mvn clean install

Maven installe les binaires compilés dans un dépôt local (par exemple, ~/.m2/repository). Il recherche les binaires dans ce dépôt avant d'extraire depuis le dépôt central Maven.

Remarque: Cette bibliothèque dépend de google-http-java-client et google-oauth-java-client. Lorsque vous travaillez sur une nouvelle version des trois bibliothèques qui n'est pas encore publiée dans Maven Central, vous devez les compiler dans l'ordre suivant:

  1. google-http-java-client
  2. google-oauth-java-client
  3. google-api-java-client La compilation dans cet ordre garantit que Maven récupère les binaires compilés pour compilation de bibliothèque dépendante.

Processus de révision du code

Télécharger le script "upload.py"

Télécharger le script upload.py et, si vous le souhaitez, l'ajouter à votre PATH.

La première fois que vous exécutez upload.py, vous êtes invité à saisir une mot de passe spécifique à l'application:

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

Préparer votre code en vue de son examen

Avant d'envoyer le code pour examen, vous devez exécuter Clirr pour intercepter le code les problèmes de compatibilité dans votre code. Si des erreurs sont signalées, vous devez corrigez-les ou mettez à jour le fichier clirr-ignored-differences.xml.

mvn -q clirr:check

Vous devez également exécuter l'outil FindBugs pour détecter les bugs dans le code. En cas d'erreurs sont signalés, vous devez les corriger ou mettre à jour le . Notez que FindBugs est très lent.

mvn findbugs:check

Une fois que votre modification a réussi tous les tests, ajoutez-la à l'index (l'ensemble de données de préproduction ):

git add .

Vérifiez bien que tous les fichiers que vous avez ajoutés, modifiés ou supprimés sont visibles. dans l'index:

git status

Dans le résultat git status, consultez la section intitulée "Modifications à valider".

Démarrer la révision du code

Lorsque vous êtes prêt pour examen, créez un problème sur codereview.appspot.com: 

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

Une fois que vous avez apporté d'autres modifications, préparez les nouvelles. Pour importer un nouveau correctif, Par exemple, pour obtenir le numéro 123456, exécutez la commande suivante: 

upload.py --rev=HEAD -i 123456

Pour plus d'options, exécutez upload.py --help.

Si vous préférez la version classique de GitHub le workflow, vous avez probablement dupliqué le dépôt GitHub et créé une branche pour cette nouvelle fonctionnalité ou correction de bug. Lorsque vous envoyer le code examiner les demandes de votre duplication, assurez-vous qu'elle est synchronisée avec le dépôt en amont. Pour en savoir plus, consultez l'aide GitHub sur la synchronisation d'une duplication.

Vous pouvez également utiliser download.py pour les ensembles de modifications validés localement.

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

Réviseur de code

Si vous êtes un réviseur de code, importez et testez des ensembles de modifications avant de les approuver, puis valider et transférer les ensembles de modifications vers le dépôt distant.

Importation d'un ensemble de modifications

Pour détecter les erreurs le plus tôt possible, assurez-vous d'extraire les dernières modifications du dans votre arborescence de travail. Assurez-vous que votre arbre de travail est propre et votre index est vide.

Pour extraire et fusionner les derniers commits du dépôt distant:

git pull

Pour vérifier le contenu de votre arborescence de travail et de votre index:

git status

Pour importer un correctif dans votre clone Git local:

  1. Ouvrez le problème sur codereview.appspot.com.
  2. Pour le correctif en question, recherchez "Télécharger les fichiers bruts". en haut à droite patch.
  3. Cliquez sur "RAW". pour obtenir l'URL du fichier à importer.
  4. Enregistrez le fichier diff brut sur votre ordinateur local sous un nom tel que issue123456.diff.
  5. Accédez à votre arborescence de travail Git locale et appliquez la valeur "diff" à l'aide de la commande patch. :
patch -p1 < issue123456.diff

Pour vérifier que vous avez importé les valeurs diff appropriées, exécutez une commande git diff dans votre arbre de travail.

Tester l'ensemble de modifications

Pour exécuter les tests et procéder à l'installation, utilisez la commande suivante:

mvn clean install checkstyle:check

Approuver un ensemble de modifications sur codereview.appspot.com

En général, le code ne peut pas être transféré vers le dépôt GitHub tant que l'examinateur de code que le code est prêt. À ce stade, la convention est de répondre avec le message "LGTM" (Tout semble correct.)

Validation du code...

Important:Avant de valider votre code, extrayez les dernières modifications arborescence de travail et mettre à jour votre arborescence de travail avec le dernier commit de GitHub dépôt:

git pull

S'il y a des conflits, résolvez-les, puis assurez-vous de faire en sorte que tous les tests passer à nouveau.

Pour valider le code localement: 

git commit

Saisissez un message semblable à celui-ci (en supposant que vous corrigez ou implémentez Problème 123, tel qu'indiqué dans le GitHub Issue Tracker):

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

Avant le premier deux-points et la description:

  • Si vous résolvez un problème dans l'Issue Tracker, indiquez le numéro du problème, comme indiqué.
  • S'il s'agit d'une modification pour une succursale particulière, incluez le numéro de succursale.
  • Vous serez le committer de cet engagement, mais merci de mentionner le fait que l'auteur de la modification en le marquant comme author (--author=<author>).

Après la description, incluez toujours un lien vers le problème dans la revue de code sur votre site. Ce lien est important, car sans lui, il n'existe aucun moyen pratique à déterminer l'examen de code associé à un commit, ce qui est utile pour maintenir un historique de la discussion.

Pour transférer la modification dans le dépôt GitHub:

git push

Si, pendant git push, vous recevez un message d'erreur indiquant que des mises à jour sont refusées (par exemple, vous avez oublié d'exécuter git pull), voici comment fusionner vos données avec les dernières modifications et déployez vos modifications dans le dépôt distant: 

git pull
git commit
git push

Clôture du problème

Veillez à fermer le problème dans l'outil de revue de code. Pour ce faire :

  1. Sélectionnez le problème sur codereview.appspot.com.
  2. Cliquez sur le "X" qui se trouve en haut à gauche, juste avant « Id ».

Annuler les correctifs d'un ensemble de modifications

Si, pour une raison quelconque, vous décidez de ne pas valider un ensemble de modifications que vous avez importé, utilisez la la commande suivante pour la supprimer. Attention: Toutes vos modifications locales seront effacées. 

git checkout -- .