Soumission de correctifs

Cette page décrit le processus complet de soumission d'un correctif au projet Android Open Source (AOSP), y compris comment demander une révision et suivre vos modifications avec Gerrit .

Conditions préalables

Pour commencer, assurez-vous d'avoir effectué les opérations suivantes :

Ressources

  • Pour plus de détails sur Repo et Git, consultez la page Outils de contrôle de source .
  • Pour plus d'informations sur les différents rôles au sein de la communauté Android Open Source, consultez la page Rôles du projet .
  • Pour obtenir des informations sur les licences concernant la contribution de code à la plate-forme Android, consultez la page Licences .

Pour les contributeurs

Authentification avec le serveur

Si vous partagez une adresse IP avec d'autres utilisateurs, des quotas peuvent être déclenchés même pour des modèles d'utilisation réguliers. Cela peut se produire lorsque, par exemple, de nombreux utilisateurs synchronisent de nouveaux clients à partir de la même adresse IP dans un court laps de temps. L'accès authentifié utilise un quota distinct pour chaque utilisateur, quelle que soit l'adresse IP. Pour en savoir plus sur l'activation de l'accès authentifié, consultez Utilisation de l'authentification .

Démarrer une branche Repo

Pour chaque modification que vous avez l'intention d'apporter, démarrez une nouvelle branche dans le référentiel Git concerné :

repo start NAME .

Vous pouvez démarrer plusieurs branches indépendantes en même temps dans le même référentiel. La branche NAME est locale à votre espace de travail et n'est incluse ni sur Gerrit ni dans l'arborescence source finale.

Faire votre changement

Modifiez les fichiers sources et validez vos modifications.

Validez les modifications dans votre dépôt local avec ces commandes :

git add -A
git commit -s

Modifier les descriptions

  • Ligne 1 : Titre

    Fournissez un résumé d'une ligne (50 caractères maximum )

    Ce format est utilisé par Git et Gerrit pour divers affichages. C'est la partie la plus importante et la plus dense de votre message de commit. Pensez à utiliser des préfixes pour décrire la zone que vous avez modifiée, suivi d'une description de la modification que vous avez apportée dans ce commit, comme celui-ci qui a ui comme préfixe :

    ui: Removes deprecated widget

  • Ligne 2 : Vide

    Gardez cette ligne vide, toujours.

  • Ligne 3 : Corps

    Écrivez une description plus longue en commençant par cette ligne.

    Cela doit être encapsulé à 72 caractères maximum. Décrivez quel problème le changement résout et comment. Bien que cela soit facultatif lors de l'implémentation de nouvelles fonctionnalités, cela sera très utile pour les autres plus tard s'ils se réfèrent à ce changement, en particulier pour le débogage.

    Incluez une brève note de toutes les hypothèses ou informations de base qui pourraient être importantes lorsqu'un autre contributeur travaille sur cette fonctionnalité.

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

Voici un exemple de message de validation :

Line 1, Headline - a short description

Line 3, Body - Add the detailed description of your patch here. Use as many lines
as needed. You can write an overall description, then list specifics.

I6e3c64e7a:Added a new widget.
I60c539a8f:Fixed the spinning image.
Pour lire un blog sur les bonnes descriptions de commit (avec des exemples), consultez Comment écrire un message de commit Git par Chris Beams.

Téléchargement sur Gerrit

Après avoir validé votre modification dans votre historique personnel, téléchargez-la sur Gerrit avec cette commande :

repo upload

Si vous avez démarré plusieurs branches dans le même référentiel, vous êtes invité à sélectionner celles à télécharger.

Après un téléchargement réussi, Repo vous fournit l'URL d'une nouvelle page sur Gerrit . Cliquez sur le lien que Repo vous donne pour afficher votre correctif sur le serveur de révision, ajouter des commentaires ou demander des réviseurs spécifiques pour votre correctif.

Demander un avis

Une fois que vous avez téléchargé vos modifications sur Gerrit, le correctif doit être examiné et approuvé par les propriétaires de code appropriés. Localisez les propriétaires de code dans les fichiers OWNERS .

Pour rechercher les propriétaires de code appropriés et les ajouter en tant que réviseurs pour votre modification, procédez comme suit.

  1. Sélectionnez le lien SUGGÉRER LES PROPRIÉTAIRES dans l'interface utilisateur Gerrit pour afficher une liste des propriétaires de code pour les fichiers de votre correctif.

    suggérer un lien aux propriétaires dans Gerrit
    Figure 1. Lien de suggestion de propriétaires dans Gerrit
  2. Ajoutez les propriétaires de code de la liste en tant que réviseurs pour votre correctif.

Pour déterminer l'état des fichiers de votre correctif, recherchez les icônes suivantes à côté des fichiers du correctif.

  • (icône de coche) : approuvé par le propriétaire du code
  • (icône en forme de croix) : non approuvé par le propriétaire du code
  • (icône de l'horloge) : en attente d'approbation par le propriétaire du code
Figure 2. Exemple de fichiers avec des icônes indiquant l'état d'approbation du propriétaire du code

Téléchargement d'un correctif de remplacement

Supposons qu'un examinateur examine votre correctif et demande une petite modification. Vous pouvez modifier votre commit dans Git, ce qui entraîne un nouveau correctif sur Gerrit qui a le même ID de modification que l'original.

git add -A
git commit --amend

Lorsque vous téléchargez le correctif modifié, il remplace l'original à la fois sur Gerrit et dans votre historique Git local.

Résolution des conflits de synchronisation

Si d'autres correctifs sont soumis à l'arborescence source qui entrent en conflit avec le vôtre, rebasez votre correctif sur le nouveau HEAD du référentiel source. Pour ce faire, exécutez cette commande :

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.

Si le rebase automatique échoue, effectuez un rebase manuel.

repo rebase

Un autre outil pour gérer le conflit de rebase est git mergetool . Lorsque vous avez fusionné avec succès les fichiers en conflit, exécutez cette commande :

git rebase --continue

Une fois le rebasage automatique ou manuel terminé, exécutez le repo upload référentiel pour soumettre votre correctif rebasé.

Après l'approbation d'une soumission

Une fois qu'une soumission a franchi le processus d'examen et de vérification, Gerrit fusionne automatiquement la modification dans le référentiel public. Les autres utilisateurs peuvent exécuter la repo sync pour extraire la mise à jour dans leurs clients locaux respectifs.

Pour les projets en amont

Android utilise un certain nombre d'autres projets open source, tels que le noyau Linux et WebKit, comme décrit dans Android Software Management . Pour la plupart des projets qui résident sous external/ , effectuez les modifications en amont, puis informez les responsables Android de la nouvelle version en amont qui contient vos modifications.

Vous pouvez également télécharger des correctifs qui entraînent le suivi d'une nouvelle version en amont. Notez que ces changements peuvent être difficiles à apporter si le projet est largement utilisé dans Android, comme la plupart des plus grands mentionnés ci-dessous, qui sont généralement mis à niveau à chaque version.

Un cas particulier intéressant est Bionic. Une grande partie du code provient de BSD, donc à moins que le changement ne concerne un code nouveau pour Bionic, veuillez faire un correctif en amont, puis extraire un tout nouveau fichier du BSD approprié.

Noyau Android

Préférez faire toutes les modifications en amont. Pour obtenir des conseils généraux, suivez les consignes de contribution au noyau Android .

ICU4C

Apportez toutes les modifications au projet ICU4C sur external/icu4c sur la page d'accueil ICU-TC . Voir Soumettre des bogues ICU et des demandes de fonctionnalités pour en savoir plus.

LLVM/Clang/Compilateur-rt

Apportez toutes les modifications aux projets liés à LLVM ( external/clang , external/compiler-rt , external/llvm ) sur la page Infrastructure du compilateur LLVM .

mksh

Apportez toutes les modifications au projet MirBSD Korn Shell sur external/mksh soit en envoyant un e miros-mksh mail à miros-mksh sur le domaine mirbsd.org (aucun abonnement requis pour y soumettre) ou sur Launchpad .

OpenSSL

Apportez toutes les modifications au projet OpenSSL sur external/openssl sur la page OpenSSL .

V8

Soumettez toutes les modifications apportées au projet V8 sur external/v8 sur la page de parution V8 . Voir Contribuer à V8 pour plus de détails.

WebKit

Apportez toutes les modifications au projet WebKit dans external/webkit sur la page WebKit . Démarrez le processus en déposant un bogue WebKit . Dans le bogue, utilisez Android pour les champs Plate - forme et Système d'exploitation uniquement si le bogue est spécifique à Android. Les bogues sont beaucoup plus susceptibles de retenir l'attention des réviseurs après l'ajout d'un correctif proposé et l'inclusion de tests. Voir Contribution de code à WebKit pour plus de détails.

zlib

Apportez toutes les modifications au projet zlib dans external/zlib sur la page d'accueil zlib .