Vous n'avez pas encore de notification

Page d'accueil

Options d'affichage

Abonné

Actualités

Abonné

Des thèmes sont disponibles :

Thème de baseThème de baseThème sombreThème sombreThème yinyang clairThème yinyang clairThème yinyang sombreThème yinyang sombreThème orange mécanique clairThème orange mécanique clairThème orange mécanique sombreThème orange mécanique sombreThème rose clairThème rose clairThème rose sombreThème rose sombre

Vous n'êtes pas encore INpactien ?

Inscrivez-vous !

Fork et pull request : la participation open source par l'exemple

Ci-gît YAML
Fork et pull request : la participation open source par l'exemple

La participation aux projets open source est en général perçue comme complexe, souvent à cause de l'outil de gestion de versions Git. Mais lorsqu'il s'agit de proposer de petites modifications, tout peut se faire simplement en ligne via des plateformes comme GitHub.

Participer à un projet open source peut se faire de bien des manières : en parlant de l'initiative autour de soi, en aidant à la documentation, à la traduction, au financement, en assistant l'équipe lors d'évènements, etc. 

Git : un petit outil qui change la vie (quand on le maîtrise)

S'il n'est pas nécessaire de savoir développer, il faut parfois faire preuve d'un certain formalisme et utiliser des outils spécifiques. Cela permet à l'équipe en charge de mieux prendre en compte les remontées de la communauté, d'en assurer le suivi. Et surtout éviter que tout ne soit perdu dans des milliers de commentaires et emails.

Pour cela, les projets open source ont souvent recours à des plateformes mêlant fonctionnalités pour développeurs et services communautaires. Dans le domaine du logiciel, on pense à des outils comme GitLab ou GitHub, qui ont pour point commun de se reposer sur un même outil créé par Linus Torvalds en 2005 : Git.

Ce gestionnaire de versions distribué a rapidement montré son intérêt au-delà du code, permettant de gérer tout aussi bien l'évolution de documents, seul ou en équipe, et pourquoi pas des textes de loi. Mais c'est un outil en ligne de commandes, qui n'est pas toujours simple à prendre en main par les débutants.

Les applications et plateformes qui l'utilisent proposent donc en général des interfaces graphiques simples pour guider le néophyte dans les méandres des commits, forks et autres pull requests.

Notre dossier sur la maîtrise de Git et de ses plateformes :

Une petite participation pour commencer

Pour vous montrer qu'il peut être facile de participer à un projet de la sorte, nous nous sommes lancé un défi : proposer une application à intégrer au nouveau gestionnaire de paquets de Microsoft, winget. Ce dernier repose sur une base communautaire maintenue via GitHub. Un guide explique comment participer. 

Avant de démarrer, il y a quelques petites choses à savoir et à faire. Tout d'abord, il faudra vous créer un compte GitHub si vous n'en avez pas. Le service est gratuit, notamment pour l'hébergement de projets open source.

Pendant la procédure, Microsoft vous demandera d'accepter son Contributor License Agreement (CLA) pour s'assurer que la contribution est faite à titre personnel, ou avec l'accord de votre employeur. Qu'il s'agît bien d'une contribution originale (pas de reprise d'un tiers sans son accord), qu'elle peut être analysée/utilisée, etc.

L'entreprise dispose d'ailleurs d'un code de conduite open source accompagné d'une FAQ. Des précautions qui peuvent paraître excessives, mais qui sont de plus en plus courantes dans de gros projets open source pour éviter tout problème, encadrer les pratiques des contributeurs et les échanges avec la communauté. 

Création d'un manifeste

Sur GitHub, winget se découpe en deux projets. Tout d'abord winget-cli, l'application elle-même, diffusée sous licence MIT. Puis winget-pkgs, qui contient la liste des applications qu'il est possible d'installer. Elle prend la forme de manifestes, des fichiers texte basés sur le format YAML pensé pour être facilement lisible.

Les règles à respecter sont détaillées ici. L'exemple est le suivant :

Id: string # publisher.package format
Publisher: string # the name of the publisher
Name: string # the name of the application
Version: string # version numbering format
License: string # the open source license or copyright
InstallerType: string # enumeration of supported installer types (exe, msi, msix, inno, wix, nullsoft, appx)
Installers:
  - Arch: string # enumeration of supported architectures
    Url: string # path to download installation file of the specified version
    Sha256: string # SHA256 calculated from installer

On le voit, il s'agit de simples variables suivies d'une valeur, avec une indentation (sous la forme d'espaces uniquement) lorsque c'est nécessaire, permettant par exemple de déclarer différents fichiers d'installation. Microsoft propose même un outil prêt à l'emploi ainsi qu'un script PowerShell pour vous simplifier la vie.

Ils sont organisés dans le répertoire de la manière suivante :

manifests/nom_de_l_éditeur/nom_de_l_application/numéro_de_version.yaml

Avant de soumettre un manifeste, il faut respecter quelques règles. La première est bien entendu d'éviter les doublons : si une contribution a déjà été faite ou est en cours, n'en ajoutez pas. Ensuite, il faut créer votre manifeste, puis le tester. C'est seulement après que vous pourrez l'envoyer.

Création et test du manifeste

Dans notre cas, nous avons décidé de proposer le gestionnaire de clés de sécurité Yubikey de Yubico. Après vérification, il n'était pas disponible ou en traitement. La première étape est de déterminer comment l'installer de manière « silencieuse », sans que l'utilisateur n'ait à interagir. Le plus souvent, cela passe par l'ajout de l'argument /S ou /silent. Parfois, lancer l'exécutable avec /? permet d'avoir la liste des possibilités. Ce n'était pas le cas ici.

Nous avons donc téléchargé l'outil, l'avons lancé avec /S, avec succès. Étape suivante : remplir le manifeste. Nous ne l'avons pas fait via les outils automatiques de Microsoft, un simple éditeur de texte suffit. Veillez à y écrire en anglais, winget étant prévu pour une utilisation internationale, sans traduction locale pour le moment.

Voici le résultat obtenu pour la version actuelle (1.1.5) :

Id: Yubico.YubikeyManager
Version: 1.1.5
Name: Yubikey Manager
AppMoniker: yubimgr
Tags: 2fa, security, auth
Description: Official tool to configure FIDO2, OTP and PIV functionality on your YubiKey
Homepage: https://www.yubico.com/products/services-software/download/yubikey-manager/
Publisher: Yubico
License: Copyright (c) Yubico 2020. All Rights Reserved.
Installers:
- Arch: x64
    Url: https://developers.yubico.com/yubikey-manager-qt/Releases/yubikey-manager-qt-1.1.5-win64.exe
    Sha256: 719F266675616F21070EA11FE0B1C75AF02C54494288E7E0164B4280BE90CE33
    InstallerType: exe
    Switches:
      Silent: /S
      SilentWithProgress: /S

La plupart des éléments peuvent être récupérés sur le site de l'éditeur. Pensez à tous les préciser. Les tags doivent aider à la découverte de l'application lors d'une recherche. L'empreinte SHA-256 se calcule facilement avec la commande Get-FileHash sous PowerShell (voir ci-dessous). Vous pouvez également passer par la commande winget hash. Nous avons utilisé notre propre outil CheckHash

Hash Powershell

Une fois le fichier créé, il faut le valider et le tester avec les commandes suivantes :

winget validate nom_du_manifeste.yaml
winget install -m nom_du_manifeste.yaml

La seconde indique à winget de tenter une installation depuis votre manifeste plutôt que sa base de données. Si vous obtenez le message « installé correctement », vous pouvez le soumettre à l'équipe via GitHub. Sinon, pensez à vérifier que vous n'avez pas des espaces mal formés avec un outil de validation YAML. 

Participation via Git, un peu de théorie

Avant de passer à la suite, voici quelques notions et termes à connaître concernant Git. Ce que nous allons réaliser se nomme pull request (PR ou requête de tirage). Une procédure détaillée dans le manuel officiel qui consiste à créer une version modifiée du code original puis de proposer (request) à son auteur de la reprendre (pull).

Chaque code source est contenu dans un dépôt (repository). Chaque modification apportée est nommée commit. Plusieurs branches peuvent co-exister, mais il y a au minimum une branche principale (master). On peut en créer autant qu'on le souhaite, permettant de travailler sur plusieurs modifications à la fois.

Pour une application donnant l'heure, on pourrait créer une branche « ajouter-date » dans laquelle on modifierait le code pour fournir la date. Une autre « ajouter-meteo » ou « changer-fuseau-horaire ». Toute la « magie » de Git, c'est que plusieurs développeurs peuvent travailler en parallèle sur leur propre branche (parfois à plusieurs).

Git Pull-request Workflow
Crédits : GitHub

Lorsque le travail est terminé, il suffit de fusionner les branches (merge). La procédure de pull request est ce qui permet à un contributeur extérieur de proposer des modifications. Chacun peut donc apporter sa pierre à l'édifice.

Cela se fait en trois étapes :

  • On créé une copie du code originel (un fork)
  • On créé une branche pour y effectuer les modifications sans risque
  • On génère et on envoie la PR depuis cette branche

Heureusement, pour de petites participations, GitHub facilite la procédure.

Fork, pull request et soumission de manifeste

Vous n'avez même pas à télécharger ou installer Git. Tout peut se faire en ligne. La première étape est donc de créer un fork du dépôt originel. Il s'agit de récupérer tous les fichiers dans un dépôt lié à votre compte. Vous pourrez ainsi le modifier à votre guise puis effectuer vos modifications.

GitHub Pull request Winget ForkGitHub Pull request Winget Fork

Vous pouvez même faire tout en une seule étape. Rendez-vous sur la page du projet winget-pkgs en étant connecté à votre compte GitHub. Cliquez sur Add file > Create new file (voir ci-dessus). Le fork a été créé dans votre compte, un fichier vide est ouvert. Il faut le nommer. Dans notre cas :

manifests/Yubico/YubikeyManager/1.1.5.yaml

Entrez ensuite le contenu du manifeste tel que vous l'avez testé et validé. Il faudra donner un nom à cette modification (commit), compréhensible par les équipes de winget. Nous optons pour « Add YubikeyManager 1.1.5 ». Cliquez sur Propose new file pour la valider, elle sera alors créée dans la branche « patch-1 » de votre fork.

Vous serez alors invité à la transformer en PR. Dans cette dernière, un texte a été créé automatiquement avec quatre cases à cocher (d'un « x ») pour confirmer que vous avez bien accepté l'accord de contribution CLA, vérifié que l'application n'était pas déjà proposée, que vous avez validé et testé le manifeste. 

GitHub Pull request Winget ForkGitHub Pull request Winget Fork

Vérifiez une dernière fois tous les éléments, que toutes les cases sont cochées, vous pouvez ensuite la valider en cliquant sur Create pull request. Les robots de Microsoft analyseront la PR pour vérifier qu'elle est conforme et fonctionnelle, et que votre accord CLA a bien été donné. En cas de problème, un message sera affiché.

Il vous faudra alors répondre dans les commentaires, l'équipe venant de temps en temps régler les cas en attente. Cela peut néanmoins prendre quelques jours. Si tout va bien, votre proposition sera acceptée puis intégrée. Il sera alors possible d'installer l'application correspondant au manifeste que vous avez créé depuis winget.

Pensez à le mettre à jour quand de nouvelles versions seront disponibles. Si ce n'est pas le cas, un autre pourra le faire à votre place. L'aspect collaboratif de l'open source, c'est aussi ça.

67 commentaires
Avatar de BarbossHack Abonné
Avatar de BarbossHackBarbossHack- 21/08/20 à 06:48:22

Bon article :yaisse:
Il manquerait pourquoi pas une partie « terminal » avec quelques commandes git, on ne peut pas toujours faire ses PR uniquement via l’éditeur Web

Avatar de David_L Équipe
Avatar de David_LDavid_L- 21/08/20 à 06:51:50
BarbossHack

C'était un peu trash pour le premier tuto, mais il y en aura d'autres :D

Avatar de letter Abonné
Avatar de letterletter- 21/08/20 à 07:05:33

Deux petits ajouts:

  • le client Github Desktop est bien pratique pour les débutants qui découvrent.
  • considérer qu'on ne peut pas vraiment faire de "revert" mais plutôt considérer qu'on créé une branche à partir du commit précédent dont on veut repartir. Beaucoup de débutants ont du mal avec cela.
Avatar de David_L Équipe
Avatar de David_LDavid_L- 21/08/20 à 07:11:31
letter

J'ai opté pour une solution sans le client GitHub Desktop pour simplifier la procédure (j'avais commencé avec, mais pour ce projet c'était ajouter 4/5 paragraphes de textes et pas mal de notions pour pas grand chose). Comme dit plus haut, c'est de toutes façons le début d'une série d'articles sur le sujet :chinois:

Pour le second point, git reset FTW :D

Avatar de fofo9012 Abonné
Avatar de fofo9012fofo9012- 21/08/20 à 07:26:45

C'est pour moi qui n'arrive pas à comprendre les PR, je vais lire tout ça !

Avatar de Kwacep Abonné
Avatar de KwacepKwacep- 21/08/20 à 07:58:09
David_L

Super article, j'ai tellement de mal à trouver de vrai tuto sur la bonne démarche à suivre sur git :incline:
J'attends le reste avec impatience.

Avatar de xillibit Abonné
Avatar de xillibitxillibit- 21/08/20 à 08:04:13

Il y a aussi l’application gitKraken si on n'aime pas trop utiliser la ligne de commande

Avatar de David_L Équipe
Avatar de David_LDavid_L- 21/08/20 à 08:08:08
xillibit

Oui ou l'intégration aux IDE qui est en général assez complète

Avatar de Le_CuLtO Abonné
Avatar de Le_CuLtOLe_CuLtO- 21/08/20 à 08:23:13
Kwacep

Ce site interactif est très bien fait, et ça va des concepts de base à des notions un peu plus avancées:
https://learngitbranching.js.org

Avatar de wpayen Abonné
Avatar de wpayenwpayen- 21/08/20 à 08:31:36

J'attends avec impatience l'article sur les Flows où la communauté va se déchirer entre Git Flow, Github Flow, One Flow, etc.

Et aussi sur "est-ce que l'on squash" ?

Il n'est plus possible de commenter cette actualité.
Page 1 / 7
  • Introduction
  • Git : un petit outil qui change la vie (quand on le maîtrise)
  • Une petite participation pour commencer
  • Création d'un manifeste
  • Création et test du manifeste
  • Participation via Git, un peu de théorie
  • Fork, pull request et soumission de manifeste
S'abonner à partir de 3,75 €