Envoyer des modifications de code

Cette page décrit l'intégralité du processus d'envoi d'une modification de code au projet Android Open Source (AOSP), y compris comment demander un examen et suivre vos modifications.

AOSP s'appuie sur Gerrit, un système d'examen du code basé sur le Web pour les projets qui utilisent Git.

Signer les contrats de licence pour les contributeurs

Avant de contribuer à l'AOSP en modifiant le code, vous devez lire Contrats de licence et en-têtes des contributeurs et signer l'un des contrats suivants :

Créer une branche

Pour chaque modification de code que vous souhaitez apporter, procédez comme suit :

  1. Créez une branche dans le dépôt Git concerné. Une branche n'est pas une copie des fichiers d'origine. Il s'agit d'un pointeur vers un commit spécifique, ce qui facilite la création de branches locales et le passage de l'une à l'autre. En utilisant des branches, vous pouvez identifier les modifications apportées à chacune d'elles. Exécutez cette commande pour démarrer une branche :

    repo start BRANCH_NAME

    Vous pouvez démarrer plusieurs branches indépendantes en même temps dans le même dépôt. La branche BRANCH_NAME est locale à votre espace de travail et n'est incluse ni dans Gerrit ni dans l'arborescence source finale. Les branches sont également spécifiques au projet dans lequel vous vous trouvez. Par conséquent, si vous devez modifier des fichiers dans différents projets dans le cadre de la même modification, vous aurez besoin d'une branche dans chaque projet dans lequel vous modifiez des fichiers.

  2. (Facultatif) Vérifiez que la branche a été créée :

    repo status .

    La branche que vous venez de créer doit s'afficher. Exemple :

    project frameworks/native/                      branch mynewbranch

Apporter et tester votre modification

Pour effectuer et tester votre modification, procédez comme suit :

  1. Pour vous assurer de travailler avec le codebase le plus récent, synchronisez l'intégralité du codebase :

    repo sync

    Si vous rencontrez des conflits lors de la synchronisation, reportez-vous aux étapes 2 à 4 de Résoudre les conflits de synchronisation.

  2. Recherchez le code à modifier. Pour trouver du code, pensez à utiliser Android Code Search. Vous pouvez utiliser la recherche de code Android pour afficher le code source AOSP tel qu'il est présenté lorsque vous l'utilisez réellement. Pour en savoir plus, consultez Premiers pas avec Code Search. Pour afficher tout le code de la dernière branche de version AOSP dans la recherche de code Android, accédez à https://cs.android.com/android/platform/superproject/.

  3. Modifier ou ajouter des fichiers sources. Pour toute modification apportée :

  4. Créer Android

  5. Testez votre compilation.

Préparer et valider votre modification

Un commit est l'unité de base du contrôle des révisions dans Git. Il se compose d'un instantané de la structure de répertoire et du contenu des fichiers pour l'ensemble du projet. Pour valider votre modification, procédez comme suit :

  1. Par défaut, Git enregistre les modifications que vous apportez, mais ne les suit pas. Pour indiquer à Git de suivre vos modifications, vous devez les marquer ou les mettre en scène pour les inclure dans un commit. Exécutez cette commande pour préparer la modification :

    git add -A

    Cette commande permet de suivre les modifications que vous avez apportées à des fichiers.

  2. Prenez les fichiers dans la zone de préparation et validez-les ou stockez-les dans votre base de données locale :

    git commit -s

    Par défaut, un éditeur de texte s'ouvre et vous êtes invité à fournir un message de commit.

  3. Fournissez un message de commit au format suivant :

    • Ligne 1 : titre. Fournissez un résumé de la modification sur une ligne (50 caractères maximum). Envisagez d'utiliser des préfixes pour décrire la zone que vous avez modifiée, suivis d'une description de la modification que vous avez apportée dans ce commit. Par exemple, voici un exemple contenant une modification de l'interface utilisateur :

      ui: Removes deprecated widget

    • Ligne 2 : ligne vide. Laissez une ligne vide après le titre.

    • Ligne 3 : corps. Fournissez une description longue qui ne dépasse pas 72 caractères par ligne. Décrivez le problème que la modification résout et comment. Bien que le corps soit facultatif, il est utile aux autres utilisateurs qui ont besoin de se référer à la modification. Veillez à inclure une brève note sur les hypothèses ou les informations générales qui pourraient être importantes lorsqu'un autre contributeur travaille sur cette fonctionnalité.

    Pour lire un blog sur les bonnes descriptions de commit (avec des exemples), consultez How to Write a Git Commit Message (Comment rédiger un message de commit Git).

  4. Enregistrez le commit.

Un ID de modification unique, ainsi que votre nom et votre adresse e-mail fournis lors de l'repo init, sont automatiquement ajoutés à votre message de commit.

Importer la modification pour examen

Une fois que vous avez validé votre modification dans votre historique Git personnel, importez-la dans Gerrit :

  1. Exécutez la commande suivante pour importer tous vos commits dans tous vos projets :

    repo upload

    Toutes les modifications apportées à tous les projets sont incluses dans l'importation.

    .

    Vous êtes invité à exécuter des scripts de hook.

  2. Appuyez sur a, puis sur Entrée.

    Vous êtes invité à approuver l'importation :

    Upload project frameworks/native/ to remote branch android16-release:
branch BRANCH_NAME ( 1 commit, Wed Aug 7 09:32:33 2019 -0700):
       ff46b36d android codelab change
to https://android-review.googlesource.com/ (y/N)?

  3. Appuyez sur y, puis sur Entrée pour approuver l'importation.

Vous devriez recevoir un message semblable à remote: SUCCESS.

Demander un examen

Une fois l'importation réussie, Repo vous fournit un lien vers vos modifications dans Gerrit. Cliquez sur le lien pour afficher vos modifications sur le serveur d'examen, ajouter des commentaires ou demander des réviseurs spécifiques pour vos modifications. Toutes les modifications apportées au code doivent être examinées par les propriétaires du code concerné.

Pour demander un examen :

  1. Dans Gerrit, cliquez sur SUGGEST OWNERS (Suggérer des propriétaires) :

    Suggérer un lien vers les propriétaires dans Gerrit

    Figure 1 : Lien "Suggérer des propriétaires" dans Gerrit.

    La boîte de dialogue de l'examinateur s'affiche. Cette boîte de dialogue contient une liste des propriétaires du code qui peuvent examiner votre modification.

  2. Cliquez sur un propriétaire du code pour l'ajouter à votre révision.

    Le bouton ENVOYER est activé.

  3. (Facultatif) Saisissez l'adresse e-mail des autres personnes que vous souhaitez voir examiner votre modification.

  4. Cliquez sur ENVOYER pour envoyer la modification pour examen.

Les propriétaires du code examinent vos modifications de code et, si elles sont acceptées, les sélectionnent et les fusionnent dans la branche de développement interne.

Déterminer l'état d'une modification

Pour déterminer l'état des fichiers de votre modification, recherchez les icônes suivantes à côté des fichiers de la modification :

  • (icône en forme de coche) : approuvé par le propriétaire du code
  • (icône Croix) : Non approuvé par le propriétaire du code
  • (icône horloge) : en attente d'approbation par le propriétaire du code

La figure suivante montre ces icônes d'état appliquées aux fichiers d'une modification :

Exemple de fichiers avec des icônes indiquant l'approbation du propriétaire du code

Figure 2. Exemple de fichiers avec des icônes indiquant l'approbation du propriétaire du code.

Résoudre les problèmes signalés et importer une modification de remplacement

Si un réviseur demande une modification de votre mise à jour, vous pouvez modifier votre commit dans Git, ce qui génère un nouveau patchset sur la même modification.

Pour résoudre les problèmes signalés et modifier votre changement :

  1. Suivez les étapes 2 à 4 de Apporter et tester vos modifications.

  2. Exécutez les commandes suivantes pour modifier votre changement :

    git add -A
git commit --amend

  3. Importez votre modification.

Lorsque vous importez la modification modifiée, elle remplace l'original à la fois sur Gerrit et dans votre historique Git local.

Résoudre les conflits de synchronisation

Si d'autres modifications sont envoyées à l'arborescence source et qu'elles sont en conflit avec les vôtres, vous recevez un message indiquant que vous avez des conflits. Pour résoudre les conflits :

  1. Assurez-vous d'utiliser le code le plus récent :

    repo sync .

    La commande repo sync récupère les mises à jour du serveur source, puis tente de rebaser automatiquement votre HEAD sur le nouveau HEAD distant.

  2. Si le rebasage automatique échoue, effectuez un rebasage manuel :

    repo rebase .

  3. Résolvez les conflits de fusion. Si vous n'avez pas de méthode préférée pour résoudre les conflits de fusion, vous pouvez utiliser git mergetool pour résoudre manuellement les conflits entre les fichiers.

  4. Une fois les fichiers en conflit corrigés, exécutez cette commande pour appliquer les nouveaux commits :

    git rebase --continue

Envoyer la modification

Une fois qu'une contribution a passé le processus d'examen et de validation, le propriétaire du code l'envoie pour vous, soit sur la branche sur laquelle la modification a été examinée, soit dans une branche interne.

Une fois votre envoi fusionné, vous pouvez consulter le tableau de bord Android Continuous Integration pour savoir quand vos envois sont intégrés à l'arborescence.