Aller au contenu
Alpine JS Open-Source Git GitHub

J'ai participé pour la première fois à un projet Open-Source : Alpine JS

Pierre

7 min de lecture

Toujours pour le développement de ce blog j'ai réalisé un audit OWASP (sécurité) et implémenté les fix nécessaires. Parmi ceux-ci j'ai intégré les CSP pour Content Security Policy, il s'agit de headers http de sécurité pour se protéger contre les attaques XSS. Les CSP c'est un gros morceau et si j'ai le courage j'écrirai un article là dessus car c'est très intéressant.
Pour ce projet de blog j'ai utilisé la stack TALL (Tailwind, Alpine JS (notre ami concerné par cet article), Laravel, Livewire).

En intégrant les CSP moi et mon ami Claude on s'est rendu compte d'une chose : Chrome m'affiche un avertissement de feature dépréciée, vraiment rien de grave mais ça me fait chuter mon score Lighthouse bonnes pratiques de 100 à 81, après le travail effectué sur l'accessibilité, le seo, les bonnes pratiques et les perfs, ça me faisait *****

[Deprecation] Shared Storage API is deprecated and will be removed in a future release.

Bon je vous passe le détail de ce bug mineur et sa résolution, si ça vous intèresse vous retrouverez ma PR ici.

Je n'avais jamais participé à un projet Open-Source du haut de mon expérience de dev junior et c'était ici la bonne occasion. Ça m'a permis d'aller un peu plus loin avec Git et Github, et je vais vous partager la procédure.

Premièrement on lit de README.md du repo en question, la façon de contribuer est fournie :

Contribution Guide:

Quickstart

  • clone this repo locally
  • run npm install & npm run build
  • Include the /packages/alpinejs/dist/cdn.js file from a <script> tag on a webpage and you're good to go!

OK pas bien compliqué, alors je me lance :

git clone https://github.com/alpinejs/alpine.git alpinejs-bug

cd alpinejs-bug

npm install

Je crée un fichier HTML très basique et qui permet de reproduire mon bug :

<!DOCTYPE html>
<html>
<head>
    <script src="./packages/alpinejs/dist/cdn.js" defer></script>
    <script src="./packages/csp/dist/cdn.js" defer></script>
    <title>Alpine CSP sharedStorage Bug</title>
</head>
<body>
<div x-data="{ count: 0 }">
    <button x-on:click="count = count + 1">
        Clicks: <span x-text="count">0</span>
    </button>
</div>
<script type="module">
    window.Alpine = Alpine;
</script>
</body>
</html>

Je build et lance un serveur local :

npm run build
npx serve .

J'ouvre Chrome et vérifie que mon bug se reproduit bien, c'est le cas.

Je fix le bug

L'idée ici est d'apporter les modifs au projet local afin de résoudre le bug, pour ma part ça se résume à une ligne de code (oui c'est le début de la gloire ! 😂).

// packages/csp/src/parser.js                             
  - if (key === "styleMedia") return
  + if (key === "styleMedia" || key === "sharedStorage") return

Je reste convaincu que dans l'open-source pas besoin d'un gros fix pour contribuer. C'est justement sa force, chacun apporte sa pierre à l'édifice.

La contribution

Maintenant qu'on a notre fix on souhaite le partager.

Fork + Pull Request est le workflow standard pour contribuer à un projet open source auquel on n'a pas accès en ecriture. On ne peut pas pusher directement sur alpinejs/alpine, il faut passer par notre propre fork.

GitHub ne permet de créer une PR que depuis une branche d'un repo qu'on controle — d'ou l'etape "fork" prealable.

Voici la procédure étape par étape :

  • on va sur le repo auquel on souhaite contribuer, pour ma part alpinejs/alpine
  • on clique sur le bouton "Fork" en haut à droite
  • on conserve les options par défaut et on clique sur "create fork"
  • on obtient un repo perso basé sur le repo initial

Une fois qu'on a obtenu notre repo sur lequel on a la main normalement on devrait faire un git clone sur notre machine locale, moi j'ai été trop rapide et j'ai déjà clone le repo initial, alors il va falloir apporter quelques ajustements avec Git :

  • git remote rename origin upstream -> on renomme le remote actuel (le repo officiel) en "upstream"
  • git remote add origin https://github.com/VOTRE_USERNAME/votre-depot-fork.git -> on ajoute notre fork comme remote "origin"
  • git remote -v -> on vérifie, la réponse attendue est origin : votre fork | upstream : le repo officiel
  • git checkout -b fix/csp-shared-storage-deprecation -> on crée une branche pour le fix

Maintenant il nous reste à commit nos modifs qu'on avait déjà apportées plus haut, soit en CLI, soit via votre IDE (Jetbrains, VS Code, ...) :

  • git add packages/csp/src/parser.js -> on ajoute les fichiers modifiés pour le commit, ici c'est mon fichier, vous adaptez avec les votres
  • git commit -m "fix(csp): skip sharedStorage when enumerating globalThis properties" -> on crée le commit, l'option -m permet d'ajouter un message
  • git push -u origin fix/csp-shared-storage-deprecation -> on push sur notre repo sur la branche qu'on a crée

Voici la version visuelle :

aperçu d'un éditeur de texte de programmeur

  1. on est bien sur la branche qu'on a crée
  2. on va sur l'onglet "Commit" et on coche nos fichiers modifiés
  3. on ajoute un message de commit
  4. commit and push

Si c'est votre premier push, Git vous demandera de vous authentifier.

Il nous reste maintenant à créer notre Pull Request ou PR pour les initiés. On pourrait le faire via notre IDE mais la plupart des organisations activent des restrictions d'accès OAuth sur GitHub. PhpStorm utilise une app OAuth pour interagir avec GitHub, et cette organisation (Alpine JS dans mon cas) bloque les apps tierces non approuvées. Alors on passe directement par GitHub.

  • on va sur notre fork : https://github.com/PierreBultez/alpinejs
  • vous devriez voir un bandeau jaune en haut avec votre branche recente et un bouton "Compare & pull request" -> on clique dessus
  • Si le bandeau n'apparait pas, cliquez sur "Contribute" > "Open pull request"

Ca ouvrira l'interface de creation de PR directement sur GitHub, sans passer par l'app OAuth de PhpStorm.

Ce qu'on doit vérifier / remplir :

  • Base repository : organisation/repository / branche main ou master (la branche principale du projet initial)
  • Head repository : votre_username/votre-repo / branche fix/csp-shared-storage-deprecation (la branche qu'on a crée, ici c'est la mienne)
  • Titre : un titre qui illustre bien votre correctif : une IA vous aidera bien
  • Description : une description brève et précise. ici on ne raconte pas sa vie, les mainteneurs n'ont pas que ça à faire. On explique la raison de notre PR.

Aperçu d'une pull request sur GitHub

Une fois enregistrée la PR sera crée sur le repository initial du projet vous aurez la fierté d'aller l'admirer, d'autres utilisateurs ou contributeurs pourront commenter dessus.

liste de pull request d'un projet open source

détail d'une pull request sur github

Et après ?

C'est là qu'on attend notre récompense : les mainteneurs peuvent accepter votre PR directement, demander des ajustements, ou parfois ne pas repondre pendant des semaines. C'est normal, les projets open source sont souvent maintenus sur le temps libre. Patience !

Si vos modifs sont très pertinentes alors vous décrocherez le saint graal : un mainteneur mergera votre code, vous aurez alors votre tête dans la liste des contributeurs et vous pourrez vous la péter comme jamais.

Discussion

Laisser un commentaire