Comment contribuer

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Accords de licence des contributeurs

Avant d'accepter vos correctifs de code, vous devez nous soumettre un contrat de licence pour les particuliers ou un accord d'entreprise :

  • Si vous êtes un particulier qui écrit le code source d'origine et que vous êtes certain de détenir la propriété intellectuelle, envoyez un ACP individuel.
  • Si vous travaillez pour une entreprise, celle-ci doit envoyer un CLA pour entreprise 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 que nous le recevrons, nous pouvons vous ajouter à la liste officielle des contributeurs.

Présentation de l'envoi de correctifs

Pour ajouter du code à ce projet, procédez comme suit:

  1. Signez un contrat de licence Contributor, comme 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 demande de fonctionnalité) dans notre Issue Tracker GitHub. S'il n'y en a pas déjà un, créez-en un et attribuez-le à vous-même.
  5. Consultez le code, créez un problème sur codereview.appspot.com et terminez le processus d'examen du code. Vous trouverez ci-dessous des instructions détaillées sur tous ces processus.
  6. Une fois votre code examiné et validé, validez-le. Si vous n'êtes pas un contributeur officiel, un contributeur transfère votre ensemble de modifications dans le dépôt 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 qu'un système de distribution binaire.
  • Nous utilisons codereview.appspot.com pour les examens de code. (Notez toutefois que, dans l'outil codereview.appspot.com, le terme "problème" désigne une demande d'examen du code, tandis que dans l'outil GitHub Issue Tracker, un "problème" correspond à une demande de fonctionnalité ou à un rapport de bug.

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

Configurer l'environnement de développement

Conditions préalables

  1. Installez Java 6. Vous devrez peut-être définir votre variable JAVA_HOME.
  2. Installez Maven. (Ce document part du principe que vous connaissez les principes de base des commandes Maven.)
  3. (Facultatif) Installez le SDK Android et définissez votre variable ANDROID_HOME sur l'emplacement d'installation pour 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 depuis Git

Pour pouvoir récupérer le code de GitHub, vous devez vous authentifier auprès de GitHub à l'aide du protocole HTTP ou SSH. Avant de poursuivre avec les instructions ci-dessous, lisez les instructions de GitHub pour apprendre à utiliser le clonage HTTPS ou SSH. Si vous souhaitez en savoir plus sur Git en général, Pro Git est une excellente ressource.

Vérifier le code

Utiliser le protocole HTTPS

Pour vérifier le dépôt de la bibliothèque dans la branche "maître" de développement, 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 la branche de développement "maître", assurez-vous de disposer d'un accès en écriture au dépôt GitHub, puis exécutez la commande suivante:

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

Pour passer à une autre branche, par exemple 1.12:

git checkout --track origin/1.12

Pour revenir à la branche principale:

git checkout master

Pour récupérer les dernières modifications du dépôt GitHub et mettre à jour votre arborescence de travail local vers le dernier commit:

git pull

Maven

Installer les services Google Play

La première fois que vous configurez le projet, vous devez installer le fichier google-play-services.jar. Procédez comme suit :

  1. Lancez Eclipse et sélectionnez Window > Android SDK Manager ou exécutez android dans la ligne de commande.
  2. Faites défiler la liste des packages jusqu'en bas, puis sélectionnez Services supplémentaires et services Google Play.
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 de les récupérer dans le dépôt central Maven.

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

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

Processus d'examen du code

Télécharger le scriptupload.py

Téléchargez le script upload.py et ajoutez-le éventuellement à votre PATH.

La première fois que vous exécutez upload.py, vous êtes invité à saisir un 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éparation de votre code en vue de son examen

Avant d'envoyer le code pour examen, vous devez exécuter Clirr pour détecter les problèmes de rétrocompatibilité dans votre code. Si des erreurs sont signalées, vous devez les corriger ou mettre à 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. Si des erreurs sont signalées, vous devez les corriger ou mettre à jour le fichier Findbugs-exclude.xml. Notez que FindBugs est très lent.

mvn findbugs:check

Une fois que la modification a passé tous les tests, ajoutez-la à l'index (zone de préproduction Git):

git add .

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

git status

Dans la sortie git status, vérifiez la section intitulée"Changes to be commit" (Modifications à valider).

Démarrer la révision du code

Lorsque vous êtes prêt pour l'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 ...

Après avoir effectué d'autres changements, effectuez la mise à jour. Pour importer un nouveau correctif, par exemple pour le numéro 123456, exécutez la commande suivante :

upload.py --rev=HEAD -i 123456

Pour accéder à d'autres options, exécutez upload.py --help.

Si vous préférez le workflow GitHub classique, vous avez probablement dupliqué le dépôt GitHub et créé une branche pour cette nouvelle fonctionnalité ou ce correctif de bug. Lorsque vous envoyez des requêtes de vérification de code depuis votre propre copie, assurez-vous que votre copie est synchronisée avec le dépôt en amont. Pour plus d'informations, consultez l'aide GitHub sur la synchronisation d'une fourchette.

Vous pouvez également utiliser le fichierupload.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 validez et transférez les ensembles de modifications vers le dépôt distant.

Importer un ensemble de modifications

Pour détecter les erreurs de manière anticipée, veillez à extraire les dernières modifications du dépôt distant dans votre arborescence de travail. Assurez-vous que votre arborescence de travail est propre et que 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 et index indexés:

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, cherchez la mention "Télécharger brut" en haut à droite de la spécification du correctif.
  3. Cliquez sur "raw&quot" pour afficher 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 différence à l'aide de la commande patch:
patch -p1 < issue123456.diff

Pour vérifier que vous avez importé la bonne différence, exécutez une commande git diff dans votre arborescence de travail.

Tester l'ensemble de modifications

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

mvn clean install checkstyle:check

Approbation d'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 le réviseur n'est pas satisfait du fait qu'il est prêt. À ce stade, la convention consiste à répondre avec le message "LGTM".

Valider le code

Important:Avant de valider votre code, importez les dernières modifications dans votre arborescence de travail et mettez à jour votre arborescence de travail vers le dernier commit à partir du dépôt GitHub:

git pull

En cas de conflit, résolvez-les, puis veillez à ce que tous les tests soient de nouveau réussis.

Pour valider le code localement :

git commit

Saisissez un message semblable à celui-ci (en supposant que vous résolviez ou appliquiez le problème n° 123, comme indiqué dans l'outil Issue Tracker de GitHub):

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

Avant le premier deux-points et la description:

  • S'il s'agit d'un correctif dans l'Issue Tracker, incluez le numéro du problème, comme indiqué.
  • S'il s'agit d'une modification pour une branche particulière, incluez le numéro de la branche.
  • Vous serez le committer de ce commit, mais veuillez attribuer le crédit de l'auteur de la modification en le marquant comme author (--author=<author>).

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

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

git push

Si au cours de git push vous recevez un message d'erreur indiquant que les mises à jour ont été refusées (vous avez peut-être oublié d'exécuter git pull), voici comment fusionner ces dernières avec les dernières modifications et les transférer 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 d'examen du code. Procédez comme suit :

  1. Sélectionnez le problème sur le site codereview.appspot.com.
  2. Cliquez sur la croix (X) qui se trouve en haut à gauche, avant l'identifiant "Id.".

Annuler la correction 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é, exécutez la commande suivante pour le supprimer. Attention: Cette opération entraîne la suppression de toutes les modifications locales.

git checkout -- .