Envoyer les modifications du code

Cette page décrit le processus complet de soumission d'une modification de code au projet Android Open Source (AOSP), y compris la procédure à suivre pour demander un examen et suivre vos modifications.

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

Signer les contrats de licence des contributeurs

Avant d'apporter des modifications de code pour AOSP, vous devez lire les contrats de licence et les en-têtes du contributeur et signer l'un des accords suivants:

Démarrer une branche

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

  1. Démarrez une nouvelle branche dans le dépôt Git approprié. Une branche n'est pas une copie des fichiers d'origine. C'est un pointeur vers un commit spécifique, ce qui facilite la création de branches locales et le basculement entre elles. En utilisant des branches, vous pouvez identifier les modifications les unes des autres. Exécutez la commande suivante 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 se trouve localement dans votre espace de travail et n'est incluse ni sur 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 les fichiers de différents projets dans le cadre d'une 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. Par exemple :

    project frameworks/native/                      branch mynewbranch

Effectuez et testez 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, effectuez une synchronisation de l'ensemble du codebase:

    repo sync

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

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

  3. Modifiez ou ajoutez des fichiers sources. Pour toute modification apportée:

  4. Développez Android.

  5. Testez votre build.

Préparer et valider votre modification

Un commit est l'unité de base du contrôle des révisions dans Git. Il consiste en un instantané de la structure du 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 demander à Git de suivre vos modifications, vous devez les marquer ou les préparer afin de les inclure dans un commit. Exécutez la commande suivante pour préparer la modification:

    git add -A

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

  2. Prenez les fichiers dans la zone de préproduction 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é d'une ligne de la modification (50 caractères maximum). Pensez à utiliser des préfixes pour décrire la zone que vous avez modifiée, suivis d'une description des modifications que vous avez apportées dans ce commit, comme dans l'exemple suivant contenant une modification de l'interface utilisateur:

      ui: Removes deprecated widget

    • Ligne 2: ligne vide. Faites suivre le titre avec une ligne vide.

    • Ligne 3: Corps. Fournissez une longue description en dur avec un maximum de 72 caractères. Décrivez quel problème le changement résout et comment. Bien que le corps soit facultatif, il est utile pour les autres utilisateurs qui doivent se référer au changement. Veillez à inclure une brève note des hypothèses ou des informations générales qui pourraient être importantes lorsqu'un autre contributeur travaille sur cette fonctionnalité.

    Pour lire un article de blog sur les bonnes descriptions de commit (avec des exemples), consultez la section Comment écrire 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 repo init, sont automatiquement ajoutés à votre message de commit.

Importer la modification pour examen

Après avoir validé votre modification dans votre historique Git personnel, importez-la dans Gerrit:

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

    repo upload

    Toutes les modifications apportées à l'ensemble des 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 main:
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 terminée, Repo vous fournit un lien vers vos modifications dans Gerrit. Cliquez sur le lien pour afficher vos modifications sur le serveur de vérification, ajouter des commentaires ou demander des réviseurs spécifiques pour votre modification. Toutes les modifications apportées au code doivent être examinées par les propriétaires de code appropriés. Pour demander un examen:

  1. Dans Gerrit, cliquez sur SUGGEST OWNERS (SUGGÉRER DES PROPRIÉTAIRES) :

    Suggérer un lien de propriétaire dans Gerrit

    Figure 1 : Suggérer un lien de propriétaire dans Gerrit.

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

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

    Le bouton ENVOYER est activé.

  3. (Facultatif) Saisissez l'adresse e-mail de la personne à qui vous souhaitez envoyer la modification.

  4. (Facultatif) Cliquez sur +1 à côté de "Envoi automatique" pour envoyer automatiquement la modification une fois que vous avez reçu des approbations. Si vous ne cliquez pas sur ce bouton, un employé de Google doit envoyer la modification pour vous.

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

Les propriétaires de code examinent les modifications apportées à votre code et vous envoient des commentaires pour que vous puissiez les appliquer ou les approuver.

Déterminer l'état d'une modification

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

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

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

Exemple de fichiers avec des icônes montrant 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 commentaires et importer une modification de remplacement

Si un réviseur demande à modifier votre mise à jour, vous pouvez modifier votre commit dans Git, ce qui entraîne un nouveau patchset lors de la même modification.

Pour traiter les commentaires et modifier votre modification:

  1. Suivez les étapes 2 à 4 de la section Effectuer et tester votre modification.

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

    git add -A
git commit --amend

  3. Importez votre modification.

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

Résoudre les conflits de synchronisation

Si d'autres modifications sont soumises à l'arborescence source et qu'elles entrent en conflit avec les vôtres, vous recevez un message vous informant 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 la rebase automatique échoue, effectuez une rebase manuelle:

    repo rebase .

  3. Résoudre 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 la commande suivante pour appliquer les nouveaux commits:

    git rebase --continue

Envoyer la modification

Une fois que le code a été examiné et validé, un examinateur Google doit transmettre le code à votre place. Les autres utilisateurs peuvent exécuter repo sync pour importer la mise à jour dans leurs clients locaux respectifs.

Une fois vos envois fusionnés, vous pouvez accéder au tableau de bord Intégration continue Android pour vérifier à quel moment vos envois sont intégrés à l'arborescence.