Aller au contenu principal

Pull Requests

Configurer votre environnement local

Étape 1 : Dupliquer un projet

Fork the project on GitHub and clone your fork locally.

$ 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

Most pull requests opened against the electron/electron repository include changes to either the C/C++ code in the shell/ folder, the JavaScript code in the lib/ folder, the documentation in docs/api/ or tests in the spec/ folder.

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

Note that multiple commits get squashed when they are landed.

Ecrire un messages de modification

Un bon message de modification/commit doit décrire le changement et sa raison. The Electron project uses semantic commit messages to streamline the release process.

Before a pull request can be merged, it must have a pull request title with a semantic prefix.

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

  • fix: don't overwrite prevent_default if default wasn't prevented
  • feat: add app.isPackaged() method
  • docs: app.isDefaultProtocolClient is now available on Linux

Common prefixes:

  • fix: A bug fix
  • feat: A new feature
  • docs: Documentation changes
  • test: Adding missing tests or correcting existing tests
  • build: Changes that affect the build system
  • ci: Changes to our CI configuration files and scripts
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • style: Changes that do not affect the meaning of the code (linting)

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

  1. La première ligne doit :
    • contain a short description of the change (preferably 50 characters or less, and no more than 72 characters)
    • ê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 de rupture

A commit that has the text BREAKING CHANGE: at the beginning of its optional body or footer section introduces a breaking API change (correlating with Major in semantic versioning). A breaking change can be part of commits of any type. e.g., a fix:, feat: & chore: types would all be valid, in addition to any other type.

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.

If you are updating tests and want to run a single spec to check it:

$ npm run test -match=menu

The above would only run spec modules matching menu, which is useful for anyone who's working on tests that would otherwise be at the very end of the testing cycle.

É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

From within GitHub, opening a new pull request will present you with a template that should be filled out. 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 pendnat 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.

Feel free to post a comment in the pull request to ping reviewers if you are awaiting an answer on something. If you encounter words or acronyms that seem unfamiliar, refer to this glossary.

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. Whenever a maintainer reviews a pull request they may request changes. These may be small, such as fixing a typo, or may involve substantive changes. Such requests are intended to be helpful, but at times may come across as abrupt or unhelpful, especially if they do not include concrete suggestions on how to change them.

Essayez de ne pas vous décourager. If you feel that a review is unfair, say so or seek the input of another project contributor. Often such comments are the result of a reviewer having taken insufficient time to review and are not ill-intended. Such difficulties can often be resolved with a bit of patience. That said, reviewers should be expected to provide helpful feedback.

Étape 11 : Approbation

In order to land, a pull request needs to be reviewed and approved by at least one Electron Code Owner and pass CI. After that, if there are no objections from other contributors, the pull request can be merged.

Félicitations et merci pour votre contribution !

Tests en intégration continue

Every pull request is tested on the Continuous Integration (CI) system to confirm that it works on Electron's supported platforms.

Ideally, the pull request will pass ("be green") on all of CI's platforms. This means that all tests pass and there are no linting errors. However, it is not uncommon for the CI infrastructure itself to fail on specific platforms or for so-called "flaky" tests to fail ("be red"). Each CI failure must be manually inspected to determine the cause.

CI starts automatically when you open a pull request, but only core maintainers can restart a CI run. If you believe CI is giving a false negative, ask a maintainer to restart the tests.