A development workspace with notes for an open-source contribution, editorial illustration
LE GUIDE

Modifier des projets open source

Un guide pour débuter dans la contribution aux projets open source.

Commencer la lecture
9 min de lecture16 imagesFrançaisPage originale
MODE DE LECTURE

Ce tutoriel illustré inclut des logiciels et du matériel anciens. Les captures expliquent le processus, mais menus, prix, exigences et disponibilité peuvent différer. Consultez la documentation liée du projet pour la version que vous utilisez.

Illustration de la modification de projets open source

Créer un fork d’un projet open source

Découvrir l’open source peut intimider les débutants, mais nous allons vous accompagner. Ce guide détaille chaque aspect du processus. Avec Bitcoiner.Guide comme terrain d’exercice, vous rédigerez un article et proposerez des changements au projet principal.

Étape 1 : créer un compte GitHub et installer les outils nécessaires

Étapes nécessaires

Vérifiez que les outils nécessaires sont installés sur votre ordinateur.

  1. Un compte GitHub : il faut un compte GitHub pour créer un fork et proposer vos changements. Créez-en un sur GitHub si nécessaire.

  2. Git : ce système de gestion de versions permet de suivre et gérer les modifications du code. Il est essentiel pour travailler avec GitHub et préinstallé sur beaucoup d’ordinateurs. Saisissez git -v dans le terminal : sa version apparaîtra s’il est installé. Sinon, consultez ce guide.

  3. Visual Studio Code : un éditeur polyvalent avec des fonctions facilitant Git. Téléchargez-le ici.

  4. Pour les sources historiques Jekyll, installez un environnement Ruby pris en charge et Bundler avant les dépendances du dépôt. Sous macOS, utilisez un Ruby distinct géré par chruby, rbenv, asdf ou un autre gestionnaire compatible, pas le Ruby système d’Apple. Vérifiez ruby -v et installez les gemmes nécessaires dans cet environnement sans employer systématiquement sudo. Sous Windows, utilisez un RubyInstaller pris en charge et sa boîte à outils de développement. Ces étapes concernent le dépôt Jekyll original, pas la refonte statique 3.0.

Informations complémentaires

L’ouverture d’un terminal dépend du système. Voici la méthode pour les trois systèmes de bureau les plus courants :

  1. Windows:
    • Par le menu Démarrer : cliquez sur Démarrer ou appuyez sur Windows, recherchez « cmd » ou « Invite de commandes » et validez avec Entrée.
    • Par Exécuter : appuyez sur Windows+R, saisissez « cmd » et appuyez sur Entrée.
  2. macOS:
    • Par Spotlight : appuyez sur Command+Space, recherchez « Terminal » et validez.
    • Par Finder : ouvrez Finder, allez dans Applications -> Utilitaires et double-cliquez sur Terminal.
  3. Linux:
    • Par la grille d’applications : selon la distribution et l’environnement, Terminal se trouve dans la grille ou le lanceur d’applications.
    • Par raccourci clavier : sur de nombreuses distributions, Ctrl+Alt+T ouvre un terminal.

Dans Visual Studio Code, quel que soit le système, ouvrez le terminal depuis View -> Terminal dans le menu supérieur.

Étape 2 : créer un fork de Bitcoiner.Guide

Un fork crée une copie du dépôt sur votre compte GitHub, afin de le modifier sans affecter le projet original.

  1. Rendez-vous sur https://github.com/BitcoinQnA/Bitcoiner.Guide.
  2. Cliquez sur « Fork » en haut à droite pour créer une copie sur votre compte.

FIG. 01Étape 2 : créer un fork de Bitcoiner.GuideIllustration de la modification de projets open source

Étape 3 : cloner le projet sur votre ordinateur

Il faut maintenant obtenir une copie locale du projet, autrement dit le « cloner ».

  1. Ouvrez votre fork. Son URL devrait être https://github.com/YOUR_GITHUB_USERNAME/Bitcoiner.Guide
  2. Cliquez sur « Code », puis sur l’icône du presse-papiers pour copier l’URL.

FIG. 02Étape 3 : cloner le projet sur votre ordinateurIllustration de la modification de projets open source

  1. Ouvrez Visual Studio Code.
  2. Cliquez sur « Source Control » dans le panneau gauche.
  3. Cliquez sur « Clone Repository ».
  4. Collez l’URL dans la boîte de dialogue et appuyez sur Entrée.

FIG. 03Étape 3 : cloner le projet sur votre ordinateurIllustration de la modification de projets open source

  1. Lors du choix du dossier, allez sur le bureau et cliquez sur « Select Repository Location ».

FIG. 04Étape 3 : cloner le projet sur votre ordinateurIllustration de la modification de projets open source

Étape 4 : créer une nouvelle branche

Créer une branche pour vos modifications est une bonne pratique collaborative, notamment en open source. Elle isole vos changements du projet principal, souvent appelé branche « main » ou « master ».

  1. Cliquez sur le nom de branche en bas à gauche, normalement master ou main.
  2. Dans la boîte de dialogue, sélectionnez Create new branch.
  3. Nommez la branche, par exemple « foundation-devices », puis appuyez sur Entrée.

FIG. 05Étape 4 : créer une nouvelle brancheIllustration de la modification de projets open source

Vous pouvez revenir à la branche principale à tout moment en cliquant sur le nom en bas à gauche et en la choisissant dans la liste.

Étape 5 : préparer le projet localement

Lisez le README actuel, le fichier de verrouillage des dépendances et les consignes de contribution avant d’installer Ruby ou Bundler. Travaillez sur une branche dédiée, exécutez les vérifications locales documentées, puis proposez une pull request. Les commandes ci-dessous décrivent le projet Jekyll original ; elles ne sont pas les instructions de construction de cette expérimentation locale de design.

Exécutons Bitcoiner.Guide sur votre ordinateur.

  1. Ouvrez le terminal de Visual Studio Code via View -> Terminal.

FIG. 06Étape 5 : préparer le projet localementIllustration de la modification de projets open source

  1. Exécutez bundle install pour installer les gemmes Ruby nécessaires.
  2. Exécutez bundle exec jekyll serve pour démarrer un serveur local.
  3. Le site est maintenant accessible à http://localhost:4000.

FIG. 07Étape 5 : préparer le projet localementIllustration de la modification de projets open source

Après clonage de ce dépôt Jekyll historique, exécutez bundle install depuis le dossier contenant Gemfile, puis bundle exec jekyll serve. Installer Bundler seul n’installe pas les dépendances du dépôt. Répétez bundle install lorsque leurs fichiers changent.

Étape 6 : modifier et enregistrer les changements

Modifions le projet en ajoutant un article intitulé « Foundation Devices » :

  1. Dans Visual Studio Code, créez un fichier au format foundation-devices.md.

FIG. 08Étape 6 : modifier et enregistrer les changementsIllustration de la modification de projets open source

  1. Ajoutez ces métadonnées en tête du fichier :
---
layout: page
title: Foundation Devices
subtitle: Sovereign computing company
---
  1. Rédigez l’article sous les métadonnées. Par exemple :

Foundation Devices est une entreprise de matériel construisant des outils centrés sur Bitcoin pour reprendre votre souveraineté numérique. Elle voulait créer une entreprise différente, axée sur l’open source et la fabrication locale. Cela commence avec Passport et Envoy, mais ce n’est que le début !

Les articles de Bitcoiner.Guide utilisent le format Markdown, un langage de balisage léger pour mettre le texte en forme. Cet excellent guide explique le gras, les listes et bien d’autres éléments.

Pour inclure des images :

  1. Placez d’abord l’image dans le dossier assets > img du projet.

FIG. 09Étape 6 : modifier et enregistrer les changementsIllustration de la modification de projets open source

  1. Utilisez ensuite la syntaxe suivante :
<p align="center">
  <img src="/assets/img/your-image-file-name.jpg" class="responsive" style="max-width: 100%; height: auto;" />
</p>
  1. Remplacez your-image-file-name.jpg par le nom du fichier image.
  2. Enregistrez avec CMD+S ou CTRL+S.
  3. Revenez au navigateur et ouvrez http://localhost:4000/foundation-devices

Nous avons transformé ceci :

---
layout: page
title: Foundation Devices
subtitle: Sovereign computing company
---
Foundation Devices is a hardware company that builds Bitcoin-centric tools that empower you to reclaim your digital sovereignty. They aimed to build a different kind of hardware company with an emphasis on Open Source and local manufacturing. This starts with Passport and Envoy – but they are just getting started!

<p align="center">
  <img src="/assets/img/foundation-devices-images.jpg" class="responsive" style="max-width: 100%; height: auto;" />
</p>

En cela :

FIG. 10Étape 6 : modifier et enregistrer les changementsIllustration de la modification de projets open source

Consultez d’autres articles .md du projet pour comprendre leur construction. Respectez son style rédactionnel pour conserver la cohérence.

Étape 7 : envoyer vos changements à GitHub

Enregistrons les changements et envoyons-les à GitHub.

  1. Cliquez sur l’icône de gestion de versions à gauche de Visual Studio Code.
  2. Les modifications figurent dans « Changes ». Cliquez sur le « + » près des fichiers pour les préparer au commit.

FIG. 11Étape 7 : envoyer vos changements à GitHubIllustration de la modification de projets open source

  1. Saisissez un message de commit en haut, par exemple « Ajouter l’article Foundation Devices », puis appuyez sur Ctrl+Enter ou Cmd+Enter sur Mac.
  2. Cliquez sur les trois points de Source Control et choisissez « Push » pour envoyer les changements à GitHub.

FIG. 12Étape 7 : envoyer vos changements à GitHubIllustration de la modification de projets open source

FIG. 13Étape 7 : envoyer vos changements à GitHubIllustration de la modification de projets open source

Étape 8 : ouvrir une pull request

Proposons enfin d’intégrer vos changements au projet original :

  1. Rendez-vous sur https://github.com/YOUR_GITHUB_USERNAME/Bitcoiner.Guide
  2. Cliquez sur « Pull request ».
  3. Cliquez sur « New pull request » ou « Compare & pull request ».

FIG. 14Étape 8 : ouvrir une pull requestIllustration de la modification de projets open source

  1. Vérifiez que « base repository » est BitcoinQnA/Bitcoiner.Guide et « head repository » YOUR_GITHUB_USERNAME/Bitcoiner.Guide.
  2. Cliquez sur « Create pull request ».
  3. Saisissez un titre et une description des changements.
  4. Cliquez de nouveau sur « Create pull request ».

FIG. 15Étape 8 : ouvrir une pull requestIllustration de la modification de projets open source

Félicitations ! Vous avez créé un fork de Bitcoiner.Guide, contribué et ouvert une pull request. Le responsable du projet, ici QnA, examinera vos changements. Il peut les accepter, demander des modifications ou en discuter avec vous.

Étapes facultatives

Étape 9 : modifier après la création d’une pull request

Vous pouvez vouloir ajouter des changements après la création, ou les responsables peuvent demander des révisions. Inutile de créer une autre pull request. Voici comment procéder :

  1. Vérifiez que vous êtes dans la bonne branche de Visual Studio Code, celle des changements initiaux et de la pull request.
  2. Effectuez les modifications supplémentaires et enregistrez les fichiers.
  3. Préparez et commitez ces changements comme à l’étape 6-7.
  4. Cliquez sur les trois points de Source Control et sélectionnez « Push ».

Les changements mettront automatiquement à jour la pull request existante sur GitHub. Inutile d’en créer une autre. Pour commenter les changements, ouvrez la pull request sur GitHub et ajoutez un commentaire à la discussion.

Étape 10 : maintenir votre fork à jour

Récupérer les mises à jour n’obtient que l’état du dépôt disponible à cet instant. Examinez et appliquez les mises à jour suivantes délibérément ; une récupération réussie ne garantit pas que le déploiement reste automatiquement à jour.

Créer un fork prend un instantané du projet à un moment donné. L’original continue toutefois d’évoluer avec les changements des autres contributeurs. Pour maintenir votre copie à jour, suivez ces étapes :

  1. Ajouter le projet original comme dépôt distant: cette étape indique à Git l’emplacement du projet original. Une seule exécution suffit.
    • Ouvrez Visual Studio Code et vérifiez que le projet Bitcoiner.Guide est ouvert.
    • Ouvrez le terminal de Visual Studio Code via View -> Terminal.
    • Saisissez git remote add upstream https://github.com/BitcoinQnA/Bitcoiner.Guide.git et validez. Cette commande ajoute le projet original comme dépôt distant nommé « upstream ».
  2. Récupérer les changements du projet original: cette étape télécharge les derniers changements de l’original sans encore les fusionner dans votre projet.
    • Dans le terminal, saisissez git fetch upstream et appuyez sur Entrée.
  3. Passer à la branche principale: fusionnez les changements dans la branche principale, pas dans la branche où vous avez effectué vos modifications.
    • Cliquez sur le nom de branche en bas à gauche de Visual Studio Code ; il devrait s’agir de votre branche de travail.
    • Dans la boîte de dialogue, choisissez la branche principale, généralement main ou master.
  4. Fusionner les changements: cette étape incorpore les changements du projet original à votre branche principale.
    • Dans le terminal, saisissez git merge upstream/main ou git merge upstream/master selon le nom de la branche principale du projet original, puis validez.

Conclusion

Contribuer à un projet open source comme Bitcoiner.Guide peut intimider, surtout au début. Ce guide complet fournit les étapes et outils nécessaires pour créer un fork, apporter des changements et proposer une pull request en confiance.

La contribution open source comprend la collaboration, l’apprentissage, le partage et l’amélioration, au-delà du code. Ne vous découragez pas si tout n’est pas parfait dès le début. La pratique vous rendra plus à l’aise. Chaque contribution, même petite, est précieuse.

À propos de l’auteur

Bonjour, je suis Bitlevi ! Je concrétise mes apprentissages sur le chemin de la souveraineté en écrivant sur Bitcoin et les outils FOSS. Contactez-moi sur Twitter ou consultez mon site. Si ce guide vous a plu et que vous souhaitez faire un don, voici mon PayNym !


Continuez votre parcours

Une question en amène une autre.

01Une transaction bloquée : attendre, l’accélérer ou l’annuler02Gérer vos pièces et vos frais

Find your next answer.

Search the complete field guide · Esc to close