Soumettre des 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 code 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 relatives à la contribution de code à la plate-forme Android, consultez la page Licences .

Pour les contributeurs

Authentification auprès du 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 source et validez vos modifications.

Validez les modifications dans votre dépôt local à l'aide de ces commandes :

git add -A
git commit -s

Modifier les descriptions

  • Ligne 1 : titre

    Fournir 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 validation. 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 celui-ci qui a ui comme préfixe :

    ui: Removes deprecated widget

  • Ligne 2 : vide

    Gardez cette ligne vide, toujours.

  • Ligne 3 : Corps

    Rédigez une description plus longue, en commençant sur cette ligne.

    Celui-ci doit contenir 72 caractères maximum. Décrivez le problème que le changement résout et comment. Bien que cela soit facultatif lors de l'implémentation de nouvelles fonctionnalités, il est 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 fond qui pourraient être importantes lorsqu'un autre contributeur travaille sur cette fonctionnalité.

Un ID de modification unique, votre nom et votre adresse e-mail, qui sont fournis lors de l' repo init du référentiel, 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), voir Comment écrire un message de commit Git par Chris Beams.

Téléchargement vers 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 fourni par Repo pour afficher votre correctif sur le serveur de révision, ajouter des commentaires ou demander des réviseurs spécifiques pour votre correctif.

Demander une révision

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 trouver 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 SUGGEST OWNERS dans l'interface utilisateur de Gerrit pour afficher une liste des propriétaires de code pour les fichiers de votre correctif.

    suggérer le lien des propriétaires dans Gerrit
    Figure 1. Lien Suggérer aux 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 dans votre patch, recherchez les icônes suivantes à côté des fichiers dans le patch.

  • (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 d'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 relecteur regarde votre patch et demande une petite modification. Vous pouvez modifier votre commit dans Git, ce qui se traduit par 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 réussi à fusionner les fichiers en conflit, exécutez cette commande :

git rebase --continue

Une fois le rebasage automatique ou manuel terminé, exécutez le repo upload du 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 du référentiel 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/ , apportez 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 à jour avec 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 une extraction d'un tout nouveau fichier à partir du BSD approprié.

Noyau Android

Préférez effectuer toutes les modifications en amont. Pour obtenir des conseils généraux, suivez les directives relatives à la contribution du noyau Android .

soins intensifs

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

CLDR

La plupart des données linguistiques d'ICU proviennent du projet Unicode CLDR . Veuillez soumettre toutes les demandes en amont à l'aide des demandes de modification CLDR et ajouter le libellé "Android".

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 en envoyant un e-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 dans external/openssl sur la page OpenSSL .

V8

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

Kit Web

Apportez toutes les modifications au projet WebKit sur external/webkit sur la page WebKit . Démarrez le processus en signalant 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 recevoir l'attention des réviseurs après l'ajout d'un correctif proposé et l'inclusion de tests. Voir Contribuer du code à WebKit pour plus de détails.

zlib

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