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 :
- Open source, libre et communs : contribuer ne nécessite pas de développer
- Apprenez à utiliser Git : les bases pour l'évolution d'un document
- Git remote : comment héberger vos documents et codes source sur un serveur
- Git : comment travailler avec plusieurs remotes
- Fork et pull request : la participation open source par l'exemple
- GitHub CLI 1.0 est disponible : comment l'installer et l'utiliser
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.
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).
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.
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.
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.
