Envoyer les modifications du code

Cette page décrit l'ensemble du processus d'envoi d'une modification de code au projet Open Source Android (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.

Signez les contrats de licence des contributeurs.

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

• En tant que contributeur individuel qui ne contribue qu'en votre nom, signez le Contrat de licence du contributeur individuel.
• En tant qu'employé d'une entreprise, assurez-vous que votre entreprise a signé le Contrat de licence pour les contributeurs professionnels vous autorisant à contribuer en son nom.

Démarrer une branche

Pour chaque modification de code que vous prévoyez d'effectuer, procédez comme suit:

1. Créez une branche dans le dépôt Git approprié. Une branche n'est pas une copie des fichiers d'origine. Il s'agit d'un pointeur vers un commit spécifique, ce qui rend la création de branches locales et le basculement entre elles une opération légère. En utilisant des branches, vous pouvez identifier les modifications les unes par rapport aux autres. 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 pour votre espace de travail et n'est pas 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 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 devrait s'afficher. Exemple :

   project frameworks/native/                      branch mynewbranch
   

Apportez la modification et testez-la

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

1. Pour vous assurer que vous travaillez avec le codebase le plus récent, effectuez une synchronisation de l'ensemble du codebase:

   repo sync
   

   Si des conflits surviennent pendant la synchronisation, consultez les étapes 2 à 4 de la section Résoudre les conflits de synchronisation.

2. Recherchez le code à modifier. Pour trouver du code, envisagez d'utiliser la recherche de code Android. Vous pouvez utiliser la recherche de code Android pour afficher le code source AOSP tel qu'il est présenté lorsque vous l'utilisez. Pour en savoir plus, consultez 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:

   • Déterminez si vous devez utiliser des options de lancement de fonctionnalités et, le cas échéant, implémentez-les pour votre nouveau code.

   • Suivez les bonnes pratiques décrites dans la section Inclure des en-têtes de licence.

   • Pour le code Java, suivez le style de code Java AOSP pour les contributeurs.

   • Certaines parties d'AOSP sont écrites en Kotlin (.kt), et vous pouvez utiliser Kotlin dans les zones de la plate-forme déjà écrites en Kotlin. Pour en savoir plus sur Kotlin sur Android, consultez le guide de style Kotlin et le guide d'interopérabilité Kotlin-Java pour les développeurs Android. Pour obtenir des conseils plus détaillés sur Kotlin, consultez le site du langage Kotlin.

   • Lorsque vous écrivez des API, suivez les Consignes relatives aux API Android. Suivez ces consignes pour comprendre le contexte des décisions d'API d'Android. Les ajouts et modifications des API de la plate-forme sont validés par Metalava.

4. Créer Android

5. Testez votre build.

Mettre en scène et valider votre modification

Un commit est l'unité de base de la gestion des versions dans Git. Il consiste en 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, mais ne suit pas les modifications que vous apportez. Pour demander à Git de suivre vos modifications, vous devez les marquer ou les préparer pour les inclure dans un commit. Exécutez cette commande pour mettre en scène la modification:

   git add -A
   

   Cette commande suit les modifications que vous avez apportées à des fichiers.

2. Prenez les fichiers de 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 validation.

3. Fournissez un message de commit au format suivant:

   • Ligne 1: titre. Fournissez un résumé en une ligne de la modification (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, comme dans l'exemple suivant contenant une modification de l'interface utilisateur:

     ui: Removes deprecated widget
     

   • Ligne 2: ligne vide. Suivez le titre par une ligne vide.

   • Ligne 3: Corps. Fournissez une description longue qui se scinde en lignes à 72 caractères maximum. Décrivez le problème que la modification résout et comment. Bien que le corps soit facultatif, il est utile pour les autres personnes qui doivent se reporter au changement. Veillez à inclure une brève note sur toute hypothèse ou information de fond qui pourrait être importante lorsqu'un autre contributeur travaillera sur cette fonctionnalité.

   Pour lire un article de blog sur les bonnes descriptions de validation (avec des exemples), consultez How to Write a Git Commit Message (Écrire un message de validation Git).

4. Enregistrez le commit.

Un ID de modification unique, ainsi que votre nom et votre adresse e-mail, qui ont été 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 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 la mise en ligne:

   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.

Un message semblable à remote: SUCCESS doit s'afficher.

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 d'examen, 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 SUGGÉRER DES PROPRIÉTAIRES:

   

   Figure 1 : Lien "Suggest owners" (Proposez des propriétaires) dans Gerrit

   La boîte de dialogue d'évaluation 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 de code pour l'ajouter à votre examen.

   Le bouton ENVOYER est activé.

3. (Facultatif) Saisissez l'adresse e-mail de toute autre personne que vous souhaitez voir consulter votre modification.

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

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

Les propriétaires du code examinent vos modifications de code et vous fournissent des commentaires pour les résoudre ou les approuver.

Déterminer l'état de la modification

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

• done (icône en forme de coche): approuvé par le propriétaire du code
• clear (icône en forme de croix) : le propriétaire du code n'a pas approuvé
• access_time (icône en forme d'horloge): approbation en attente par le propriétaire du code

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

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 une modification de votre mise à jour, vous pouvez modifier votre commit dans Git, ce qui génère un nouveau lot de correctifs pour la même modification.

Pour résoudre les problèmes soulevés et modifier votre modification:

1. Suivez les étapes 2 à 4 de la section Appliquer 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'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 vous informant de la présence de conflits. Pour résoudre les conflits:

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

   repo sync .
   

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

2. Si la 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 que vous avez corrigé les fichiers en conflit, exécutez cette commande pour appliquer les nouveaux commits:

   git rebase --continue
   

Envoyer la modification

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

Une fois votre contribution fusionnée, vous pouvez consulter le tableau de bord Intégration continue Android pour surveiller quand vos contributions sont intégrées à l'arborescence.