Aller au contenu principal

Requêtes de Pull

Configurer votre environnement local​

Étape 1 : Dupliquer un projet​

Dupliquer le projet sur GitHub et cloner votre duplicata localement.

$ git clone git@github.com:username/electron.git
$ cd electron
$ git remote add upstream https://github.com/electron/electron.git
$ git fetch upstream

Etape 2 : Construire, compiler​

Le type de système d'exploitation peut faire varier les étapes de construction et les dépendances. Reportez vous au guide dédié pour compiler Electron:

Dès que le projet est construit, vous pouvez apporter des modifications !

Step 3: Branches​

Pour un environnement de développement ordonné, créez une branche locale qui contiendra votre travail. Votre branche doit être crée directement à partir de la branche main.

$ git checkout -b my-branch -t upstream/main

Apporter des changements​

Étape 4 : Code​

La plupart des demandes pull ouvertes sur le dépôt electron/electron incluent des modifications du code C/C++ dans le dossier shell/, du code JavaScript dans le dossier lib/, de la documentation dans docs/api/ ou les tests dans le dossier spec/.

Penser à lancer régulièrement npm run lint après chaque évolution du code, pour en garantir la conformité de style du projet.

Voir coding style pour plus d'informations sur les meilleurs usages lors de modification de code dans les différentes parties du projet.

Étape 5 : modifications​

Il est recommandé de regrouper logiquement les modifications dans des commit dédiés. La plus-part des contributeurs préfèrent passer en revue les changements faits de plusieurs commit. Il est possible d'avoir autant de commit que nécessaire lors d'une proposition d'évolution - demande de Pull - .

$ git add my/changed/files
$ git commit

Veuillez noter que les commits multiples sont souvent écrasés lorsqu'ils sont déposés.

Ecrire un messages de modification​

Un bon message de modification/commit doit décrire le changement et sa raison. Le projet Electron utilise les messages de commit sémantiques pour simplifier le processus de publication.

Avant qu'une demande pull puisse être fusionnée, elle doit avoir un titre avec un préfixe sémantique.

Exemples de messages de commit avec préfixes sémantiques :

  • fix: n'écrase pas prevent_default si la valeur par défaut n'a pas été interdite
  • feat: ajoute la méthode app.isPackaged()
  • docs : app.isDefaultProtocolClient est maintenant disponible sur Linux

Préfixes usuels :

  • fix: Une correction de bogue
  • feat: Nouvelle fonctionnalité
  • docs: Modification de documentation
  • test: Ajout de tests manquants ou correction de tests existants
  • build: Changements qui affectent le système de compilation
  • ci: Modification des fichiers de configuration ou scripts de la CI
  • perf: Changements qui améliorent les performances
  • refactor: Changement qui ne corrige ni un bogue, ni ajoute une fonctionnalité
  • style: Changement qui n'affecte pas le fonctionnement du code (linting)

Plusieurs autres choses sont à garder à l'esprit lors de la rédaction d'un message de commit :

  1. La première ligne doit :
    • contenir une brève description de la modification (de préférence 50 caractères ou moins, et pas plus de 72 caractères)
    • être entièrement en minuscules à l’exception des noms propres, acronymes et les mots qui font référence au code, comme les noms de variable/fonction
  2. Garder vide la deuxième ligne.
  3. Ne pas dépasser 72 caractères pour les lignes suivantes.

Changements majeurs avec rupture de compatibilité​

Un commit qui a le texte BREAKING CHANGE: au début de ses body ou footer facultatifs introduit un changement de rupture d'API (corrélation avec Major dans le versionnage sémantique). Un changement de rupture peut faire partie de commits de n'importe quel type. par exemple, fix:, feat: & chore: seraient valides, en plus des types usuels.

Voir conventionalcommits.org pour plus de détails.

Étape 6 : Refonder - Rebase​

Une fois vos changements livrés-"committés", il est recommander d'utiliser git rebase plutôt que git merge pour réintégrer l'historique général dans votre branche de travail.

$ git fetch upstream
$ git rebase upstream/main

Cela garantit que votre branche de travail a les dernières modifications de electron/electron main.

Étape 7 : Tester​

Corrections et fonctionnalités doivent toujours être accompagnées de tests. Un guide du test est fourni pour rendre le travail plus facile. S'inspirer d'autres tests peut aussi aider.

Exécutez toujours la suite de tests complète avant de soumettre une contribution. Pour exécuter les tests:

$ npm run test

Assurez-vous que linter ne renvoie aucun problème et que tous les tests passent. Ne soumettez aucun patch ne passant pas l'un des tests.

Si vous mettez à jour les tests et que vous voulez exécuter une seule spécification pour les valider:

$ npm run test -match=menu

Ce qui précède n'exécuterai que les modules de spécification correspondant à menu, qui est utile pour ceux travaillant sur des tests qui seraient autrement à la fin du cycle de test.

Étape 8 : Pousser​

Dès que vos commit sont prêts -- tests et lint inclus --, la procédure de soumission commence par un push de votre branche vers votre fork sur Github.

$ git push origin my-branch

Étape 9 : Ouvrir la proposition d'évolution - la demande de Pull​

Depuis GitHub, en ouvrant une proposition de contribution dite --pull request--, vous aurez à remplir un caneva . Celui ci peut être trouvé ici.

Si vous ne remplissez pas ce modèle de manière adéquate, votre Pull Request pourrait être retardée dans sa fusion pendant que les "mainteners" essayent d'obtenir plus d'informations ou bien clarifier certaines ambiguïtés.

Étape 10 : Examiner et mettre à jour​

Vous recevrez probablement des commentaires ou des demandes de modifications concernant votre pull request. Ceci est une grande partie du processus de soumission, donc ne soyez pas découragé ! Certains contributeurs pourront approuver directement le pull request. D'autres pourront réagir ou émettre des commentaires détaillés. Il s’agit d’une partie nécessaire du processus afin d’évaluer si les changements sont corrects et nécessaires.

Pour apporter des modifications à un pull request existant, apportez les modifications à votre branche locale, ajouter un nouveau commit avec ces changements et poussez ceux ci dans votre fork. GitHub mettra automatiquement à jour le pull request.

$ git add my/changed/files
$ git commit
$ git push origin my-branch

Il existe un certain nombre de mécanismes plus avancés pour gérer les commits en utilisant git rebase mais ce serait au-delà de la portée de ce guide de les détailler.

N'hésitez pas à poster un commentaire dans votre pull request pour notifier aux évaluateurs si vous attendez une réponse sur un sujet particulier. Si vous rencontrez des mots ou des acronymes avec lesquels vous n'êtes pas familiers, reportez-vous à ce glossaire.

Procédure de validation et de demandes d'évolutions​

Toutes les demandes de pull nécessitent l'approbation d'un propriétaire de code Code Owner de la zone que vous avez modifiée. Chaque fois qu'un responsables passe en revue une requête pull, il peut demander des modifications. Celles-ci peuvent être minimes, comme la correction d'une faute de frappe, ou peuvent entraîner des changements substantiels. Ces révisions sont destinées à être utiles, mais peuvent parfois être perçues comme innatendues ou inutiles, surtout si elles n'incluent pas de suggestions concrètes sur comment effectuer les modifications.

Essayez de ne pas vous décourager. Si vous pensez qu'une révision est injustifiée, dites-le ou demandez la participation d'un autre contributeur de projet. Souvent, de tels commentaires sont le résultat d'un évaluateur n'ayant pas pris le temps nécessaire pour fournir une révision détaillée, sans être mal intentionnés. De telles difficultés peuvent la plupart du temps être résolues avec un peu de patience. Cela étant, les évaluateurs sont supposés fournir des commentaires utiles.

Étape 11 : Approbation​

Afin d'être approuvée, une requête pull doit être revue et approuvée par au moins un propriétaire de code Electron - Electron Code Owner - et passer la CI. Ensuite, en absence d'objections de la part d'autres contributeurs, la requête pull peut être fusionnée.

Félicitations et merci pour votre contribution !

Tests en intégration continue​

Chaque requête pull est testée sur le système d'intégration continue (CI) pour confirmer son bon fonctionnement sur les plates-formes prises en charge par Electron.

Idéalement, la requête pull passera ("être vert" - "be green") sur toutes les plates-formes de CI. Cela signifie que tous les tests passent et qu'il n'y a pas d'erreurs dans l'analyse de code. Cependant, il n'est pas rare que l'infrastructure d'intégratiçon continue échoue elle même sur des plateformes spécifiques ou que des tests dits "non fiables" - "flaky" - échouent ("passent au rouge" - "be red"). Chaque échec de la CI doit être contrôlé manuellement pour en déterminer la cause.

La CI démarre automatiquement lorsque vous ouvrez une requête de pull, mais seuls les responsables de base peuvent redémarrer une exécution de CI. Si vous pensez que CI donne un résultat faux négatif, demandez à un responsable de redémarrer les tests.