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 . Gerrit est un système de révision de code basé sur le Web pour les projets utilisant Git. Gerrit encourage une utilisation plus centralisée de Git en permettant à tous les utilisateurs autorisés de soumettre des modifications, qui sont automatiquement fusionnées si elles réussissent la révision du code. De plus, Gerrit facilite la révision, en affichant les modifications côte à côte dans le navigateur et en permettant les commentaires en ligne.

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

Configurer Git

Pour utiliser Gerrit, votre adresse e-mail doit être associée à un compte Google enregistré. Exécutez les commandes suivantes pour configurer Git avec un nom et une adresse e-mail associés à un compte Google enregistré :

git config --global user.name Your Name
git config --global user.email your_email@gmail.com
    

S'authentifier 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 sur une courte période. 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 souhaitez apporter, démarrez une nouvelle branche dans le référentiel Git concerné :

repo start NAME .

You can start several independent branches at the same time in the same repository. The branch NAME is local to your workspace and isn't included either on Gerrit or in the final source tree.

Make your change

Modify the source files, and test your changes.

For any changes made, follow License header best practices.

Commit your change

Commit the changes to your local repository with these commands:

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 commit. Pensez à 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 toujours cette ligne vide.

  • Ligne 3 : Corps

    Écrivez une description plus longue, en commençant par 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, cela sera très utile aux autres utilisateurs ultérieurs s'ils se réfèrent à ce changement, notamment pour le débogage.

    Incluez une brève note de toutes les hypothèses ou informations générales 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 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.
To read a blog about good commit descriptions (with examples), see How to Write a Git Commit Message by Chris Beams.

Upload to Gerrit

After you commit your change to your personal history, upload it to Gerrit with this command:

repo upload

If you started multiple branches in the same repository, you're prompted to select which ones to upload.

After a successful upload, Repo provides you with the URL of a new page on Gerrit. Click the link that Repo gives you to view your patch on the review server, add comments, or request specific reviewers for your patch.

Request a review

After you've uploaded your changes to Gerrit, the patch must be reviewed and approved by the appropriate code owners. Locate code owners in OWNERS files.

To find the appropriate code owners and add them as reviewers for your change, follow these steps.

  1. Select the SUGGEST OWNERS link in the Gerrit UI to see a list of code owners for the files in your patch.

    suggest owners link in Gerrit
    Figure 1. Suggest owners link in Gerrit
  2. Add code owners from the list as reviewers for your patch.

To determine the status of the files in your patch, check for the following icons next to the files in the patch.

  • (checkmark icon): Approved by code owner
  • (cross icon): Not approved by code owner
  • (clock icon): Pending approval by code owner
Figure 2. Example of files with icons showing code owner approval status

Upload a replacement patch

Suppose a reviewer looked at your patch and requested a small modification. You can amend your commit within Git, which results in a new patch on Gerrit that has the same change ID as the 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ésoudre les conflits de synchronisation

Si d'autres correctifs sont soumis à l'arborescence source et entrent en conflit avec le vôtre, rebasez votre correctif au-dessus du 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 rebase automatique ou manuel terminé, exécutez repo upload 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. D'autres utilisateurs peuvent exécuter repo sync pour extraire la mise à jour sur 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 résidant sous external/ , effectuez les modifications en amont, puis informez les responsables d'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 modifications peuvent être difficiles à apporter si le projet est largement utilisé sous Android, comme la plupart des projets plus importants mentionnés ci-dessous, qui sont généralement mis à niveau à chaque version.

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

Noyau Android

Effectuez toutes les modifications en amont. Pour obtenir des conseils généraux, suivez les directives de contribution au noyau Android et la page Développer le code du noyau pour GKI .

USI

Apportez toutes les modifications au projet ICU dans external/icu (dossiers icu4c/ et icu4j/ ) sur la page d'accueil d'ICU-TC . Voir Soumettre des bogues et des demandes de fonctionnalités ICU pour en savoir plus. Ajoutez le label « Android » à toutes les requêtes Jira en amont.

CLDR

La plupart des données linguistiques en ICU proviennent du projet Unicode CLDR . Soumettez toutes les demandes en amont selon Contribuer au CLDR et ajoutez le label « 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 soit en envoyant un e-mail à miros-mksh sur le domaine mirbsd.org (aucun abonnement requis pour y soumettre) ou sur Launchpad .

OuvertSSL

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

V8

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

Kit Web

Apportez toutes les modifications au projet WebKit dans external/webkit sur la page WebKit . Démarrez le processus en déposant un bug WebKit . Dans le bug, utilisez Android pour les champs Plateforme et OS uniquement si le bug 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 Contribuer au 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 .