Contribuer aux projets open source

Dans cet article, vous allez apprendre à contribuer à un projet open source à l’aide d’un exemple sur lequel vous allez travailler. Nous vous guiderons pour apporter une contribution au référentiel github/docs : vous familiariser avec le référentiel, identifier un domaine auquel contribuer, créer et soumettre une pull request, puis collaborer avec les mainteneurs afin que vos modifications soient acceptées.

Prendre connaissance des directives du projet

Avant de commencer, il est important de comprendre les directives et les exigences du projet.

Pourquoi les directives sont-elles importantes ?

Chaque projet dispose de ses propres conventions, normes de codage et processus de contribution, que vous devrez respecter :

•           **Exigences en termes de style et de formatage du code :** comment le code doit être formaté, conventions de nommage et règles de linting
  

•           **Directives en matière de de test :** comment exécuter les tests, quels sont les tests requis pour les nouvelles fonctionnalités et quelles sont les conventions de test
  

•           **Processus de pull request :** comment structurer votre pull request, quelles informations inclure et quelles sont les attentes en matière de révision
  

•           **Configuration du développement :** comment configurer votre environnement de développement local, les dépendances requises et les processus de build
  

•           **Signalement des problèmes :** comment signaler des bogues, demander l’ajout de fonctionnalités ou poser des questions
  

•           **Canaux de communication :** où poser des questions, discuter des modifications ou comment obtenir de l’aide auprès des mainteneurs
  

Prendre le temps de lire ces éléments vous fera gagner du temps, à vous comme aux mainteneurs, et augmentera les chances que votre contribution soit acceptée.

Trouver les directives

Pour accéder à ces directives et exigences, accédez à la liste de contrôle Normes communautaires dans l’onglet Informations. Pour notre exemple, nous utiliserons les github/docs Normes communautaires.

•           **LISEZMOI :** fournit une vue d’ensemble du projet. Le contenu peut varier, mais le fichier README aide les utilisateurs et les contributeurs à comprendre rapidement en quoi consiste le projet et comment l’utiliser, ainsi qu’à accéder à d’autres documentations.
  

•           **Code de conduite :** définit les normes de comportement acceptables pour les contributeurs et les membres de la communauté du projet, et établit les attentes ainsi que les procédures pour traiter toute infraction.
  

•           **Contribution :** fournit des directives et des instructions aux contributeurs au projet. Cela permet de rationaliser le processus de contribution en définissant des attentes claires et en favorisant une collaboration cohérente.
  

•           **Licence :** définit légalement comment d’autres peuvent utiliser, modifier et distribuer le code, en protégeant à la fois les mainteneurs et les utilisateurs grâce à des conditions clairement définies concernant le droit d’auteur et les autorisations.
  

  • Par exemple, le référentiel github/docs utilise la licence Creative Commons pour la documentation, qui est un type de licence spécifiquement destiné aux œuvres créatives. Le code logiciel dans github/docs est sous licence MIT, qui est une licence permissive permettant à quiconque d’utiliser le code qu’il contient.
  • Pour en savoir plus sur les autres types de licences courants, utilisez l’outil Choisir une licence.

•           **Stratégie de sécurité :** fournit des instructions pour signaler les vulnérabilités de sécurité aux mainteneurs du référentiel.
  

Examinez chacune des ressources disponibles pour le référentiel github/docs.

Trouver une zone où contribuer

Lors de vos premières contributions à un projet, le fait de commencer par des corrections mineures, comme des améliorations de la documentation ou de petits rapports de bogues, peut vous aider à vous familiariser avec la base de code et le flux de travail des contributeurs. Dans cet exemple, vous allez rechercher les problèmes à l’aide des étiquettes help wanted et good first issue afin de faire remonter des problèmes spécifiques ouverts aux contributeurs externes. Vous utiliserez ensuite Copilot pour fournir davantage de contexte sur le problème.

1. Accédez à l’onglet Problèmes du référentiel github/docs, puis utilisez le filtre Étiquettes et sélectionnez « aide requise » pour afficher les problèmes ouverts que les mainteneurs ont spécifiquement marqués comme nécessitant l’aide de la communauté.

2. Parcourez la liste des problèmes et trouvez-en un sur lequel vous souhaiteriez travailler.

3. En haut à droite de n'importe quelle page sur GitHub, cliquez sur le bouton à côté de la barre de recherche.

   Discussion avec Copilot s'affiche.

4. Dans la zone d’invite, entrez l’invite suivante :

   Text

   Can you summarize the key points and next steps from this issue?
   

5. Lisez le contexte fourni par Copilot, ainsi que les commentaires des autres contributeurs et des mainteneurs, pour voir si le problème est celui sur lequel vous souhaitez travailler. Si vous avez des questions précises, vous pouvez les poser directement dans le problème ou sur le Discord, l’IRC ou le Slack du projet, le cas échéant.

Créer votre propre copie d’un projet

Vous êtes maintenant prêt(e) à contribuer. Comme vous ne disposez pas des droits nécessaires pour modifier le référentiel, vous devez d’abord créer un fork : votre propre copie du référentiel, où vous pourrez apporter des modifications en toute sécurité et les soumettre par la suite aux mainteneurs pour révision. Dans cet exemple, nous allons vous expliquer comment créer un fork du référentiel github/docs.

1. Accédez au projet GitHub Docs à l’adresse https://github.com/github/docs.

2. Dans le coin supérieur droit de la page, cliquez sur Dupliquer.

3. Sous « Propriétaire », sélectionnez le menu déroulant et cliquez sur un propriétaire pour le dépôt dupliqué.

4. Par défaut, les duplications ont le même nom que leurs référentiels en amont. Si vous le souhaitez, pour mieux distinguer votre duplication, dans le champ « Nom du dépôt », tapez un nom.

5. Dans le champ « Description », vous pouvez taper la description de votre duplication.

6. Si vous le souhaitez, sélectionnez Copier la branche PAR DÉFAUT uniquement.

   Dans de nombreux scénarios de duplication, tels que la contribution à des projets open source, vous devez uniquement copier la branche par défaut. Si vous ne sélectionnez pas cette option, toutes les branches sont copiées dans la nouvelle duplication.

7. Cliquez sur Créer une duplication.

Cloner un fork d’un projet

Vous disposez désormais d’un fork du référentiel github/docs dans votre compte, mais vous devez le transférer sur votre appareil local pour commencer à travailler sur vos modifications.

1. Sur GitHub, accédez à votre fork du référentiel github/docs.

2. Au-dessus de la liste de fichiers, cliquez sur Code.

   

3. Copiez l’URL du dépôt.

   • Pour cloner le référentiel en utilisant HTTPS, sous « HTTPS », cliquez sur .

   • Pour cloner le dépôt avec une clé SSH, en incluant un certificat émis par l’autorité de certification SSH de votre organisation, cliquez sur SSH et sur .

   • Pour cloner un dépôt avec l’GitHub CLI, cliquez sur GitHub CLI et sur .

     

4. Sur Mac ou Linux, ouvrez Terminal. Sur Windows, ouvrez Git Bash.

5. Remplacez le répertoire de travail actuel par l’emplacement où vous voulez mettre le répertoire cloné.

6. Tapez git clone, puis collez l’URL que vous avez copiée précédemment. Voici ce à quoi cela ressemble, avec votre nom d’utilisateur GitHub au lieu de YOUR-USERNAME :

   Shell

   git clone https://github.com/YOUR-USERNAME/docs
   

7. Appuyez sur Entrée. Votre clone local va être créé.

Apporter des modifications à une branche de rubrique

Il est désormais temps d’apporter des modifications. Avant de commencer, il est recommandé de créer une branche de rubrique avec un nom explicite dans votre fork. Une branche de rubrique vous permet d’isoler votre travail de la branche par défaut du référentiel.

git checkout -b YOUR_TOPIC_BRANCH

git checkout -b YOUR_TOPIC_BRANCH

Une fois que vous êtes sur votre branche de rubrique, ouvrez votre éditeur de texte ou IDE préféré, puis commencez à coder. Suivez ces meilleures pratiques :

• Utilisez Copilot pour fournir des suggestions de code, ce qui renforcera votre confiance dans vos modifications.
• Documentez votre code et écrivez des tests. Ces éléments sont souvent négligés, mais ils peuvent aider à garantir que votre contribution soit fusionnée.
• Posez des questions à Copilot sur le problème pour vous aider à mieux comprendre les exigences d’implémentation.
• Utilisez Copilot pour réviser vos modifications afin de vous assurer qu’elles respectent le style de code et les exigences de documentation du projet.
• Utilisez Copilot pour obtenir de l’aide concernant les instructions de développement et de test du projet sur votre appareil local.

Validation (commit) et envoi (push) de vos modifications

Lorsque vos modifications sont prêtes, vous pouvez les ajouter à l’index et les valider dans votre référentiel. Lors de la rédaction d’un message de commit, utilisez un titre clair et concis de moins de 50 caractères qui résume ce que fait le commit. Regroupez les modifications liées dans un seul commit si possible, mais conservez les modifications non liées dans des commits distincts.

git add .
git commit -m "a short description of the change"

git add .
git commit -m "a short description of the change"

Essayez de limiter les lignes de description de vos commits à moins de 72 caractères pour une meilleure lisibilité. Une fois que vous avez validé vos modifications locales et que vous êtes prêt(e) à les pousser vers GitHub, poussez vos modifications vers le référentiel distant.

git push

git push

Envoi d’une demande de tirage

Maintenant que vous avez poussé vos modifications vers GitHub, vous êtes prêt(e) à ouvrir une pull request. Vous pouvez ouvrir une pull request pour révision même si vous n’avez pas finalisé les modifications que vous avez apportées dans votre branche. Ouvrir une pull request rapidement dans le processus de contribution permet d’informer les mainteneurs, qui pourront fournir un premier retour sur vos modifications.

1. Accédez à votre référentiel forké sur GitHub. Par exemple : https://github.com/YOUR-USERNAME/docs.
2. Vous devriez voir une invite « Comparer et effectuer une pull request » pour la branche que vous venez de pousser. Cliquez dessus.
3. Si vous ne la voyez pas, accédez à l’onglet « Pull requests » et cliquez sur « Nouvelle pull request ».
4. Assurez-vous que le référentiel base est github/docs et que la branche de base est bien la branche principale (par exemple, main).
5. Assurez-vous que le référentiel head est votre fork (YOUR-USERNAME/docs) et que la branche de comparaison est votre branche.
6. Entrez un titre et une description pour votre demande de tirage. Dans la description, faites référence au problème que votre pull request va résoudre. Par exemple : Closes: #15. Cela fournira du contexte pour votre pull request et clôturera automatiquement le problème une fois la demande fusionnée.

Travailler avec les mainteneurs

Une fois votre pull request soumise, un mainteneur du projet l’examinera et vous fera part de ses retours. Les mainteneurs du projet peuvent demander des modifications pour respecter le style ou l’architecture de la base de code, ce qui peut parfois vous obliger à remanier des parties importantes de votre travail.

• Lorsque vous recevez des retours concernant votre pull request, répondez rapidement et professionnellement, même si les critiques vous paraissent sévères. Les mainteneurs se focalisent généralement sur la qualité du code.
• Si des modifications sont demandées pour votre pull request, n’en ouvrez pas une nouvelle pour y répondre. En conservant la pull request existante et en y effectuant les modifications, vous évitez aux mainteneurs de perdre le contexte.
• Si votre pull request reste sans réponse pendant plusieurs semaines, publiez un commentaire courtois pour demander un retour. Ne mentionnez pas directement les identifiants des mainteneurs. Les mainteneurs jonglent souvent entre le travail open source et des responsabilités à temps plein, et comprendre leurs contraintes de temps favorise une meilleure collaboration.
• Si votre contribution n’est pas acceptée, demandez des retours aux mainteneurs afin de disposer du contexte nécessaire lorsque vous souhaiterez contribuer de nouveau.

Étapes suivantes

Vous savez désormais comment identifier les bons problèmes sur lesquels travailler, créer des contributions que les mainteneurs souhaitent fusionner, et naviguer dans le processus de révision des pull requests. La communauté open source sur GitHub est prête à accueillir votre perspective unique et vos compétences. Trouvez un nouveau projet qui vous enthousiasme, identifiez un problème sur lequel travailler et commencez à contribuer.