Comment contribuer

Accords de licence pour les contributeurs

Pour que nous puissions accepter vos correctifs de code, vous devez nous envoyer un contrat de licence contributeur (CLC) individuel ou professionnel :

  • Si vous êtes une personne physique rédigeant le code source original et que vous êtes certain de détenir la propriété intellectuelle, envoyez une CLC individuelle.
  • Si vous travaillez pour une entreprise, celle-ci doit envoyer un CLC de l'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 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. signer un Contrat de licence Contributeur, 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 outil de suivi des problèmes GitHub. Créez un problème s'il n'y en a pas déjà un et attribuez-le à votre propre adresse e-mail.
  5. Vérifiez le code, signalez un problème sur codereview.appspot.com et terminez la procédure de révision. Vous trouverez ci-dessous des instructions détaillées pour l'ensemble de ces processus.
  6. Une fois que votre code a été examiné et que vous avez reçu l'approbation, validez le code. Si vous n'êtes pas un Contributeur officiel, celui-ci transfère vos 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 qu'un système de distribution binaire.
  • Nous utilisons codereview.appspot.com pour les avis 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 GitHub Issue Tracker, un "problème" est une demande de fonctionnalité ou un rapport de bug.)

Si vous êtes un développeur Eclipse, utilisez le formatage de code spécifique au projet spécifié dans le répertoire .settings qui est traité automatiquement par Eclipse.

Configurer l'environnement de développement

Conditions préalables

  1. Installez Java 6. Vous devrez peut-être définir la variable JAVA_HOME.
  2. Installez Maven. (Dans ce document, nous partons du principe que vous connaissez les principes de base des commandes Maven.)
  3. (Facultatif) Installez le SDK Android et définissez la 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 à partir de Git

Pour pouvoir extraire le code de GitHub, vous devez vous authentifier auprès de GitHub via HTTP ou SSH. Avant de suivre les instructions ci-dessous, consultez les instructions GitHub expliquant comment faire vos premiers pas avec le clonage HTTPS ou SSH. Si vous souhaitez en savoir plus sur Git en général, la ressource Git Pro est une bonne ressource.

Vérifier le code

Utiliser HTTPS

Pour consulter le dépôt de la bibliothèque dans la branche "master" 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 "master" de développement, 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 basculer vers une autre branche, par exemple 1.12:

git checkout --track origin/1.12

Pour revenir à la branche principale:

git checkout master

Pour extraire les dernières modifications du dépôt GitHub et mettre à jour votre arborescence de travail locale 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 (Fenêtre > Android SDK Manager) ou exécutez android sur la ligne de commande.
  2. Faites défiler la liste des packages jusqu'en bas, puis sélectionnez Extras > Google Play services (Bonus > 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). Elle recherche les binaires de ce dépôt avant de les extraire du 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. google-http-java-client
  2. google-oauth-java-client
  3. La compilation de google-api-java-client dans cet ordre garantit que Maven récupère les binaires compilés pour la compilation de bibliothèques dépendantes.

Processus de révision du code

Télécharger le script upload.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éparer votre code pour 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-excluded.xml. (Notez que FindBugs est très lent.)

mvn findbugs:check

Une fois que votre modification a passé tous les tests avec succès, 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 sont bien reflétés dans l'index:

git status

Dans la sortie git status, consultez la section intitulée "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 ...

Une fois que vous avez apporté d'autres modifications, échelonnez-les. Pour importer un nouveau correctif, par exemple pour le numéro d'erreur 123456, exécutez la commande suivante :

upload.py --rev=HEAD -i 123456

Pour obtenir plus d'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 cette correction de bug. Lorsque vous envoyez des demandes d'examen du code à partir de votre propre copie, assurez-vous que celle-ci est synchronisée avec le dépôt en amont. Pour en savoir plus, consultez l'aide de GitHub sur la synchronisation d'une copie.

Vous pouvez également utiliser upload.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 réviseur de code, importez et testez les ensembles de modifications avant de les approuver, puis validez-les et déployez-les dans le dépôt distant.

Importer un ensemble de modifications

Pour détecter les erreurs le plus tôt possible, 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 l'arborescence et de l'index de travail:

git status

Pour importer un correctif dans votre clone Git local:

  1. Ouvrez le problème dans codereview.appspot.com.
  2. Recherchez le correctif "Télécharger à l'état brut" en haut à droite de la spécification du correctif.
  3. Cliquez sur "brute" pour obtenir l'URL du fichier à importer.
  4. Enregistrez le fichier de différences brutes sur votre ordinateur local sous un nom tel que issue123456.diff.
  5. Accédez à votre arborescence de travail Git locale et appliquez les différences à 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

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 n'est pas sûr que le code est prêt. À ce stade, la convention consiste à répondre par le message "LGTM" (Ça semble correct).

Valider le code

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

git pull

En cas de conflits, résolvez-les, puis assurez-vous que tous les tests réussissent à nouveau.

Pour effectuer un commit du code localement, procédez comme suit :

git commit

Saisissez un message semblable à celui-ci (en supposant que vous corrigez ou implémentez le problème n° 123, comme indiqué dans l'outil de suivi des problèmes GitHub):

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

Avant le premier deux-points et la description:

  • Si cela permet de résoudre un problème sur Issue Tracker, indiquez le numéro du problème tel qu'illustré.
  • S'il s'agit d'une modification pour une succursale spécifique, indiquez le numéro de la succursale.
  • Vous serez l'committer de ce commit, mais veuillez mentionner l'auteur de la modification en les marquant comme author (--author=<author>).

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

Pour déployer la modification dans le dépôt GitHub, procédez comme suit:

git push

Si, pendant git push, vous recevez un message d'erreur indiquant que des mises à jour sont refusées (vous avez peut-être oublié d'exécuter git pull), voici comment fusionner avec les dernières modifications et les transférer vers le dépôt distant : 

git pull
git commit
git push

Boucler le problème

Assurez-vous de résoudre le problème dans l'outil d'examen du code. Procédez comme suit :

  1. Sélectionnez le problème dans codereview.appspot.com.
  2. Cliquez sur le "X" situé en haut à gauche, avant "ID".

Annuler l'application d'un correctif à 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 commande suivante pour le supprimer. Attention: Toutes vos modifications locales sont littéralement effacées. 

git checkout -- .