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:
- signer un Contrat de licence Contributeur, comme décrit ci-dessus.
- Rejoignez notre groupe de discussion.
- Configurez votre environnement de développement.
- 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.
- 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.
- 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
- Installez Java 6. Vous devrez peut-être définir la variable
JAVA_HOME
. - Installez Maven. (Dans ce document, nous partons du principe que vous connaissez les principes de base des commandes Maven.)
- (Facultatif) Installez le SDK Android et définissez la variable ANDROID_HOME sur l'emplacement d'installation pour Android.
- 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 :
- Lancez Eclipse et sélectionnez Window > Android SDK Manager (Fenêtre > Android SDK Manager) ou exécutez
android
sur la ligne de commande. - 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:
- google-http-java-client
- google-oauth-java-client
- 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:
- Ouvrez le problème dans codereview.appspot.com.
- Recherchez le correctif "Télécharger à l'état brut" en haut à droite de la spécification du correctif.
- Cliquez sur "brute" pour obtenir l'URL du fichier à importer.
- Enregistrez le fichier de différences brutes sur votre ordinateur local sous un nom tel que issue123456.diff.
- 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 commeauthor
(--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 :
- Sélectionnez le problème dans codereview.appspot.com.
- 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 -- .