Rédiger une bonne demande d'extraction

Les demandes d'extraction sont comme le sang vital d'un dépôt. Ils maintiennent tout en bonne santé et en mouvement. Cette page explique comment créer une demande de pull complète et facile à examiner, ce qui augmente les chances qu'elle soit fusionnée.

Voici quelques mesures que vous pouvez prendre pour créer les meilleures relations publiques possibles.

  1. Communiquer
  2. Configurer
  3. Réduisez la taille
  4. Gardez-le propre
  5. Tester votre modification
  6. Communiquer (partie 2)

Communiquer

Avant de vous lancer et de commencer à écrire du code, il est utile de communiquer avec l'équipe de base pour qu'elle sache ce qui vous intéresse.

Si un problème vous intéresse, ajoutez un commentaire en indiquant que vous allez commencer à y travailler. Cela permet de s'assurer que plusieurs personnes ne travaillent pas sur la même chose. Un membre de l'équipe vous répondra pour confirmer qu'il s'agit bien de votre compte.

Si vous avez une idée qui n'est pas couverte par un problème, veuillez la rédiger avant de commencer à travailler. Cela permet à l'équipe de discuter de la meilleure façon de mettre en œuvre le changement avant de commencer à le créer, ce qui vous permet de gagner du temps à long terme.

Préparer l'atelier

Si vous contribuez à Blockly ou à blockly-samples pour la première fois, commencez par la page Configuration du développement.

Définir une petite limite

Essayez toujours de limiter vos modifications et de les concentrer sur un seul point. Nous préférons examiner plusieurs PR plus petits plutôt qu'un seul PR volumineux. Voici quelques bonnes règles de base:

  • Résoudre un problème N'essayez pas de résoudre plusieurs problèmes à la fois.
  • Limitez le champ d'application. En général, une demande de pull doit prendre moins de huit heures (selon votre connaissance du codebase).
  • Utilisez des commits. Si votre PR semble un peu trop importante, divisez les modifications en groupes logiques à l'aide de commits Git.

Gardez-le propre

Pourquoi se soucier du style de code ? Nous sommes dans le jeu sur le long terme, et un style cohérent facilite la maintenance. Le style fait référence à la façon dont vous nommez vos variables, mais couvre également la façon dont vous structurez votre code, écrivez des commentaires, etc. Dans la mesure du possible, nous utilisons des outils tels que eslint pour automatiser les vérifications de style.

En plus d'eslint, veuillez suivre ces guides:

Tester votre modification

Avant de créer une demande de pull, vous devez toujours vérifier que vos modifications fonctionnent, afin de ne pas avoir à revenir en arrière et à corriger les problèmes plus tard. Voici quelques idées pour tester les différentes catégories de projets:

  • Pour les plug-ins: écrivez des tests Mocha automatisés couvrant vos modifications.
  • Exemples: testez manuellement toutes les fonctionnalités que vous avez démontrées.
  • Pour les codelabs: suivez l'intégralité du tutoriel dans un environnement propre et testez tout exemple de code que vous fournissez.

Communiquer

Il s'agit de la dernière partie, et sans doute de la plus importante, de la création d'une demande de publication: rédiger le résumé.

Un résumé de communiqué de presse efficace aide les autres développeurs à examiner vos modifications, ce qui augmente les chances qu'elles soient acceptées plus rapidement.

Votre résumé doit inclure, entre autres, les éléments suivants:

  • Problème auquel votre demande de publication est liée
  • La modification apportée par votre PR
  • Comment vous avez testé votre modification.
  • Tout élément que vous souhaitez que les réviseurs examinent.
  • Toute autre information que vous pensez nécessaire aux examinateurs

Si vous suivez le modèle de PR lorsque vous créez votre demande, vous devriez être prêt. N'oubliez pas d'être aussi concis et complet que possible.

Bon codage !