Bidouilleux d'Web - Mot-clé - GitHubLe blog technique de la communauté Mozilla francophone2022-02-04T14:07:43+01:00Communauté Mozilla francophoneurn:md5:935a9b6df47b29d6dc8c2ca47296b179DotclearMDN sur GitHub, comment contribuer ?urn:md5:9e959facfe82fe566a15f9ff291707e32021-03-16T19:47:00+01:002021-03-18T10:35:57+01:00sphinxGénéralGitGitHubLocalisationMDN<p><a href="https://developer.mozilla.org/">MDN Web Docs</a> est un site collaboratif qui documente les différentes technologies web, de <a href="https://developer.mozilla.org/fr/docs/Web/HTML">HTML</a> à <a href="https://developer.mozilla.org/fr/docs/Web/CSS">CSS</a> en passant par <a href="https://developer.mozilla.org/fr/docs/Web/JavaScript">JavaScript</a>, <a href="https://developer.mozilla.org/fr/docs/Web/HTTP">HTTP</a>, les différentes API (DOM, WebGL, etc.). Pendant de nombreuses années, le contenu de MDN était organisé dans une base de données et éditable page par page via un éditeur sur le site. Fin 2020, MDN a effectué une mue et si le site n’a pas changé d’adresse, le contenu sous-jacent réside désormais sur GitHub : toute la documentation est contenue dans un dépôt Git. Après une période de gel hivernal, la localisation est aujourd’hui de nouveau possible (ce billet fait suite <a href="https://tech.mozfr.org/post/2020/12/08/Une-mise-a-jour-quant-a-la-strategie-de-localisation-pour-MDN">au précédent</a>). Bref, la méthode de contribution et les outils associés ont bien changé. Voyons ce qu’il en est ici.</p>
<h3>L’organisation</h3>
<p>Pour commencer, voyons comment s’organise la plateforme de MDN (qui n’est pas l’organisation du contenu au sein de MDN). Il existe trois dépôts Git :</p>
<ul>
<li><a href="https://github.com/mdn/yari">mdn/yari</a> : Yari est <a href="https://hacks.mozilla.org/2020/10/mdn-web-docs-evolves-lowdown-on-the-upcoming-new-platform/">le remplaçant de Kuma</a>, c’est le serveur web qui s’occupe du rendu du site tant pour le contenu des articles que pour le reste de l’interface utilisateur.</li>
<li><a href="https://github.com/mdn/content">mdn/content</a> : ici on trouve tous les documents anglophones qui constituent le contenu de référence de MDN.</li>
<li><a href="https://github.com/mdn/translated-content">mdn/translated-content</a> : enfin, ce dépôt contient les localisations, toutes locales confondues, de mdn/content. C’est ici qu’on retrouve un répertoire pour tout le contenu francophone de MDN.</li>
</ul>
<p><a href="https://tech.mozfr.org/dotclear/public/bidouilleux/mdn_yari_contribuer/mdn_repos.png" title="Schéma d'organisation des depôts Git pour MDN, mar. 2021"><img src="https://tech.mozfr.org/dotclear/public/bidouilleux/mdn_yari_contribuer/mdn_repos.png" alt="Schéma d'organisation des depôts Git pour MDN, mar. 2021" style="margin: 0 auto; display: block;" /></a></p>
<p>Comme <a href="https://tech.mozfr.org/post/2020/12/08/Une-mise-a-jour-quant-a-la-strategie-de-localisation-pour-MDN">expliqué précédemment</a>, les locales sont réparties en deux catégories : celles qui sont ouvertes aux contributions et celles qui sont « gelées ». À l’heure actuelle, le français fait partie des locales ouvertes aux contributions (avec le chinois, le japonais et le russe).</p>
<p>Après une période de transition, cette ouverture est effective depuis le 06 mars 2021.</p>
<h3>Comment contribuer ?</h3>
<p>C’est l’objet de ce billet : vous fournir les informations nécessaires pour que vous puissiez (re)commencer à contribuer à MDN, notamment à la localisation francophone du contenu.</p>
<h4>Le format</h4>
<p>Avant de plonger dans la pratique, voyons rapidement comment sont structurés les documents dans les dépôts mdn/translated-content ou mdn/content. L’arborescence des fichiers suit celle du site et correspond à celle utilisée sur le dépôt mdn/content (il n’y a pas de traduction des noms de répertoire) :</p>
<pre><code>files
<locales>
fr
<sections>
web
...
<page> // répertoire
index.html
</code></pre>
<p>Chaque page possède donc un répertoire dans lequel sont stockés les fichiers et surtout le contenu de la page : <code>index.html</code>.</p>
<p>Ce fichier ne contient pas que du HTML. En effet, il commence par un préambule de métadonnées décrites en YAML. Ces métadonnées décrivent notamment le titre, le fragment d’URL de la page (<em>slug</em>), les étiquettes associées et le lien avec la page anglaise. Par exemple :</p>
<pre><code>---
title: Structures de données
slug: Web/JavaScript/Data_structures
tags:
- Beginner
- JavaScript
- Types
translation_of: Web/JavaScript/Data_structures
original_slug: Web/JavaScript/Structures_de_données
---
</code></pre>
<p>On trouve ensuite le contenu de l’article en HTML.</p>
<h4>Contribuer occasionnellement</h4>
<p>Si vous souhaitez corriger une coquille ou contribuer sur une page en particulier, vous pouvez utiliser directement GitHub (il vous y faudra un compte pour contribuer).
Sur la page de MDN qui vous intéresse, utilisez le lien en bas de page pour vous rendre directement sur le document :</p>
<p><a href="https://tech.mozfr.org/dotclear/public/bidouilleux/mdn_yari_contribuer/mdn_yari_1_link.png" title="mdn_yari_1_link.png, mar. 2021"><img src="https://tech.mozfr.org/dotclear/public/bidouilleux/mdn_yari_contribuer/mdn_yari_1_link.png" alt="Lien de MDN vers GitHub " style="margin: 0 auto; display: block;" /></a></p>
<p>Sur GitHub, vous pouvez alors utiliser la fonctionnalité d’édition pour modifier la page :</p>
<p><a href="https://tech.mozfr.org/dotclear/public/bidouilleux/mdn_yari_contribuer/mdn_yari_2_edit.png" title="mdn_yari_2_edit.png, mar. 2021"><img src="https://tech.mozfr.org/dotclear/public/bidouilleux/mdn_yari_contribuer/mdn_yari_2_edit.png" alt="Bouton d'édition avec un crayon sur l'interface de GitHub." style="margin: 0 auto; display: block;"/></a></p>
<p>Une fois les modifications apportées, <a href="https://docs.github.com/en/github/managing-files-in-a-repository/editing-files-in-your-repository">l’interface de GitHub vous guidera</a> pour finaliser votre contribution et cela créera automatiquement une requête qui sera revue avant d’être fusionnée et publiée.</p>
<h4>Contribuer de façon plus conséquente</h4>
<p>Si vous souhaitez éditer et/ou traduire plus fréquemment ou si votre modification porte sur plusieurs documents, il sera nécessaire de mettre en place un environnement sur votre ordinateur.</p>
<h5>Prérequis</h5>
<p>Commençons par voir ce qu’il faut au préalable :</p>
<ul>
<li>Git : selon votre système d’exploitation, il est peut-être déjà installé. Sinon, vous pouvez <a href="https://git-scm.com/">le télécharger</a> pour l’installer. Il est aussi préférable d’avoir quelques notions de Git pour se lancer.</li>
<li>Compte GitHub : à l’instar des modifications mineures, il faudra un compte sur <a href="https://github.com/">https://github.com</a>.</li>
<li><a href="https://nodejs.org/en/download/">Node.js et npm</a> : le dépôt mdn/content utilise Node.js comme système de serveur web.</li>
<li>yarn : <a href="https://www.npmjs.com/package/yarn">yarn</a> est un paquet npm. C’est le gestionnaire de dépendances pour mdn/content et une fois npm installé, vous devrez lancer <code>npm install -g yarn</code> pour installer yarn.</li>
</ul>
<h5>Initialisation</h5>
<p>Il est nécessaire de récupérer les deux dépôts sur votre ordinateur : mdn/content et mdn/translated-content. Le premier nous permettra d’avoir le contenu en anglais pour comparer et surtout de pouvoir lancer le site en local pour vérifier l’affichage du contenu édité. Le second contient les documents en français que nous allons pouvoir éditer.</p>
<ol>
<li>Sur GitHub, faites un <em>fork</em> de <a href="https://github.com/mdn/content">mdn/content</a> et de <a href="https://github.com/mdn/translated-content">mdn/translated-content</a></li>
<li><p>Clonez les deux dépôts pour créer des dépôts locaux :</p>
<pre><code>git clone git@github.com:<votrenomsurgit>/content.git
git clone git@github.com:<votrenomsurgit>/translated-content.git
</code></pre></li>
<li><p>Rajoutez le dépôt de référence avec une référence distante/<em>remote</em> <code>upstream</code>. Dans les répertoires respectifs :</p>
<pre><code>// Dans le répertoire de translated-content
git remote add upstream git@github.com:mdn/translated-content.git
// Déplacez vous dans le répertoire de content
git remote add upstream git@github.com:mdn/content.git
</code></pre></li>
<li><p>Allez dans le répertoire <code>content</code>. Pour installer les dépendances, lancez :</p>
<pre><code>yarn install
</code></pre></li>
<li><p>Afin que mdn/content « sache » où se trouve le contenu du contenu traduit, on utilise un fichier d’environnement <code>.env</code> situé à la racine du répertoire <code>content</code>. Créez un fichier <code>.env</code> avec deux variables :</p></li>
</ol>
<ul>
<li><code>EDITOR</code> pour l’éditeur de texte que vous souhaitez utiliser. La variable <code>EDITOR</code> doit correspondre au chemin du programme ou à la commande lancée pour le démarrer, elle sera utilisée pour ouvrir votre éditeur via un bouton sur le site local.</li>
<li><code>CONTENT_TRANSLATED_ROOT</code> pour le chemin du répertoire du dépôt local pour translated-content.</li>
</ul>
<p>Par exemple :</p>
<pre><code> EDITOR=code
CONTENT_TRANSLATED_ROOT=../translated-content/files
</code></pre>
<ol start="6">
<li><p>Lancez le serveur avec</p>
<pre><code>yarn start
</code></pre></li>
</ol>
<p>Vous pouvez maintenant vous rendre sur votre <a href="http://localhost:5000">http://localhost:5000</a> pour parcourir le contenu de MDN. Vous pouvez éditer les fichiers sur votre système de fichier avec votre éditeur de prédilection ou utiliser les fonctionnalités de Yari qui intègre un éditeur (ou encore utiliser Yari pour lancer votre éditeur depuis le site local).</p>
<p><a href="https://tech.mozfr.org/dotclear/public/bidouilleux/mdn_yari_contribuer/local_yari.png" title="Capture de l'interface de mdn/yari en environnement local, mar. 2021"><img src="https://tech.mozfr.org/dotclear/public/bidouilleux/mdn_yari_contribuer/local_yari.png" alt="Capture de l'interface de mdn/yari en environnement local, mar. 2021" style="margin: 0 auto; display: block;" /></a></p>
<h5>Préparer une contribution</h5>
<ol>
<li><p>Si vous avez déjà fait une contribution ou si quelques jours ont passé depuis le clonage des dépôts, commencez par <a href="https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork">rafraîchir vos dépôts locaux</a> à partir des dépôts de référence/<em>upstream</em> puis relancez <code>yarn install</code>.</p></li>
<li><p>Créez une branche avec</p>
<pre><code>git checkout -b correction-coquille-fr-jean-biche
</code></pre></li>
<li><p>Modifiez et gérez vos fichiers avec Git afin de faire un ou des commits.</p></li>
<li><p>Poussez la modification sur votre <em>fork</em> avec</p>
<pre><code>git push -u origin correction-coquille-fr-jean-biche
</code></pre></li>
<li><p>Utilisez GitHub pour créer une <em>merge request</em></p></li>
<li><p>Attendez la revue puis la fusion. Ajustez éventuellement le contenu en fonction des retours.</p></li>
<li>Vous pouvez alors guetter <a href="https://whatsdeployed.io/s/16d/mdn/translated-content">What’sDeployed</a> pour savoir quand votre contribution sera visible sur https://developer.mozilla.org (pour être tout à fait précis, il peut y avoir quelques heures de décalage avec les caches CDN).</li>
</ol>
<h4>Qu’y a-t-il à faire ?</h4>
<p>Il existe de nombreuses façons de contribuer et d’aider. Voici une liste (non exhaustive) :</p>
<ul>
<li>Vous pouvez vérifier s’il existe des <a href="https://github.com/mdn/translated-content/issues?q=is%3Aissue+is%3Aopen+label%3Al10n-fr+label%3A%22good+first+issue%22"><em>issues</em> idéales pour commencer, sur le contenu francophone</a>.</li>
<li>Rapporter des bugs : en vous baladant sur MDN, si vous croisez une erreur, vous pouvez cliquer sur le lien « <em>Report a problem with this content on GitHub</em> » et indiquer ce qui est incorrect.</li>
<li>Contribuer de façon générale : si une page de MDN n’existe pas en français sur un sujet qui vous passionne, vous pouvez la traduire en français afin de la rendre accessible à plus de personnes.</li>
</ul>
<p>Bref, toute aide est la bienvenue !</p>
<h3>Ensuite</h3>
<p>Si vous souhaitez discuter ou si vous avez des questions à ce sujet, n’hésitez pas à nous rejoindre sur <a href="https://chat.mozilla.org/#/room/#l10n-fr:mozilla.org">Matrix sur le salon #l10n-fr</a>.</p>
<style>
pre { white-space: pre;}
</style>
Ma méthode de travail avec Git et GitHuburn:md5:5ee293a18744d44617ae96457bcc29842016-04-17T13:25:00+02:002016-04-17T13:25:00+02:00sphinxGénéralGitGitHubWebCompat<p><em>Cet article est une traduction de</em> <a href="http://www.otsukare.info/2016/04/14/git-workflow">Documenting my git/GitHub worklow</a> <em>écrit par <a href="http://www.la-grange.net/karl/">Karl Dubost</a>. Karl participe au projet WebCompat pour veiller à ce que les sites web fonctionnent de façon égale sur les différents navigateurs et ce billet est l’occasion de présenter la méthode de travail qu’il utilise avec Git et GitHub. Les méthodes vues ici pourront être utile pour contribuer à d’autres projets, n’hésitez pas à guetter les fichiers <code>CONTRIBUTING.md</code> des différents dépôts. ;)</em></p>
<hr />
<p>Dans le cadre de <a href="https://webcompat.com/">webcompat.com</a>, nous développons le projet à l’aide, entre autres, de l’infrastructure offerte par GitHub. Nous avons ainsi un <a href="https://github.com/webcompat/webcompat.com/">dépôt webcompat.com</a>. N’hésitez pas à <a href="https://github.com/webcompat/webcompat.com/blob/master/CONTRIBUTING.md">contribuer</a>.</p>
<p>Je ne suis pas certain de suivre la même méthode que les contributeurs principaux, mais j’ai pensé que ce serait utile de documenter la façon dont je contribue. Cet article pourra aider les débutants voire m’être utile à l’avenir.</p>
<p>Commençons avec un rapide brouillon.</p>
<p><img src="https://tech.mozfr.org/dotclear/public/images_blog/20160414-workflow-git.png" alt="Schéma du workflow" /></p>
<p>Le projet est hébergé sur : <a href="https://github.com/webcompat/webcompat.com/">https://github.com/webcompat/webcompat.com/</a></p>
<p>Pour commencer je crée un <em>fork</em> (N.D.T. d’aucuns pourront utiliser « fourche ») grâce au bouton situé en haut à droite du site.
<img src="https://tech.mozfr.org/dotclear/public/images_blog/fork.png" alt="Créer un fork avec GitHub" /></p>
<p>Ce <em>fork</em> est désormais créé :</p>
<pre><code>https://github.com/karlcow/webcompat.com/
</code></pre>
<p>Désormais, je peux créer un clone local de ce dépôt sur mon ordinateur grâce à la commande suivante :</p>
<pre><code>git clone git@github.com:karlcow/webcompat.com.git
</code></pre>
<p>Je clone ce <em>fork</em> plutôt que le projet original afin de pouvoir travailler en local <em>et</em> bidouiller différentes branches, les envoyer vers GitHub sur mon <em>fork</em> sans risquer de gêner qui que ce soit. Quand je souhaite mêler mon code à celui des autres, j’envoie alors des <em>pull requests</em> vers le dépôt principal.</p>
<p>Une fois que c’est fait, je dispose d’une version à date du dépôt et je peux commencer à travailler sur une <em>issue</em>. Prenons par exemple l’<em>issue</em> <a href="https://github.com/webcompat/webcompat.com/issues/902">902</a> (simplement pour l’exemple). Je crée une nouvelle branche sur mon clone local (voir la section suivante pour la mise à jour de mon <em>fork</em> local).</p>
<pre><code>git checkout -b 902/1
</code></pre>
<p>Pour nommer les branches, j’ai « emprunté » le protocole de <a href="https://miketaylr.com/posts/">Mike</a> :</p>
<pre><code>nom_de_branche = numéro_issue/version_de_branche
</code></pre>
<p>Ainsi, lorsque je ne suis pas satisfait de mon travail, mais que je souhaite conserver un certain historique, je peux créer une deuxième branche pour la même <em>issue</em> avec la commande <code>git checkout --b 902/2</code> et ainsi de suite. Une fois satisfait, je peux choisir d’envoyer une <em>pull request</em> depuis la meilleure branche.</p>
<pre><code>git commit -m ’#902 upgrade GitHub-Flask to 3.1.1’
requirements.txt
git commit -m ’#902 upgrade Flask-Limiter to 2.2.0’
requirements.txt
# etc
</code></pre>
<p>Une fois la journée finie, quand je souhaite passer à autre chose ou simplement partager le code, j’envoie le contenu de mon dépôt local vers mon <em>fork</em> hébergé sur GitHub.</p>
<pre><code>git push karlcow 902/1
</code></pre>
<p>Vous aurez remarqué que je n’ai pas utilisé <code>git push origin 902/1</code>, j’explique après la façon dont j’utilise des alias pour les dépôts.</p>
<p>Une fois mes commits terminés, je peux créer une <em>pull request</em> depuis <code>karlcow:902/1</code> vers <code>webcompat:master</code> :</p>
<pre><code>https://github.com/webcompat/webcompat.com/pull/920
</code></pre>
<p><img src="https://tech.mozfr.org/dotclear/public/images_blog/pull_request.png" alt="Créer une pull request avec GitHub" /></p>
<p>J’utilise ce message :</p>
<pre><code>fix #902 - 902/1 Update python module dependencies in the project.
</code></pre>
<p>et demande à Mike d’effectuer la revue du code</p>
<pre><code>r? @miketaylr
</code></pre>
<p>Ensuite, nous discutons, rejetons la modification, la modifions ou la fusionnons.</p>
<h2>Les alias de dépôt</h2>
<p>Généralement, GitHub utilise les termes suivants :</p>
<ul>
<li><code>upstream</code> pour désigner le dépôt original</li>
<li><code>origin</code> pour désigner votre propre <em>fork</em></li>
</ul>
<p>Cela était source de confusion et j’ai donc choisi une autre approche :</p>
<pre><code>git remote rename origin karlcow
git remote rename upstream webcompat
</code></pre>
<p>Cela devient beaucoup plus simple lorsque je mets à jour le projet ou que je pousse mes commits. Je sais exactement où ils vont.</p>
<pre><code># On télécharge des choses depuis le dépôt webcompat.com sur github.com
git fetch webcompat
# Je pousse ma branche vers mon propre fork sur github.com
git push karlcow nom_branche
</code></pre>
<h2>Mettre à jour mon fork local</h2>
<p>À chaque fois, lorsque j’ai terminé de travailler sur une branche ou que j’ai fini ma session de travail et que <strong>tous les commits ont été effectués</strong>, je synchronise la branche <code>master</code> de mon clone (local) avec la branche <code>master</code> de webcompat.com
Voici le vocabulaire GitHub que j’utilise généralement :</p>
<pre><code>git checkout master
git fetch upstream
git merge upstream/master
</code></pre>
<p>Transposé avec mes alias, cela donne :</p>
<pre><code>git checkout master
git fetch webcompat
git merge webcompat/master
</code></pre>
<p>Mon projet est désormais à jour et je peux créer une nouvelle branche pour la prochaine issue sur laquelle je travaillerai.</p>
<h2>Faire le ménage entre les forks locaux et distants</h2>
<p>Je crée des branches locales sur <code>~/code/webcompat.com</code> et des branches distantes sur <a href="https://github.com/karlcow/webcompat.com/">https://github.com/karlcow/webcompat.com/</a>, mieux vaut les supprimer au fur et à mesure pour éviter d’avoir une énorme liste de branches avec :</p>
<pre><code>git branch -a
</code></pre>
<p>Par exemple, si je la lance maintenant, voici le résultat que j’obtiens :</p>
<pre><code>git branch -a
264/1
396/1
* 710/3
713/1
master
r929/958
remotes/karlcow/264/1
remotes/karlcow/702/1
remotes/karlcow/710/1
remotes/karlcow/710/3
remotes/karlcow/HEAD -> karlcow/master
remotes/karlcow/master
remotes/webcompat/gh-pages
remotes/webcompat/issues/741/2
remotes/webcompat/letmespamyou
remotes/webcompat/master
remotes/webcompat/searchwork
remotes/webcompat/staging
remotes/webcompat/staticlabels
remotes/webcompat/webpack
</code></pre>
<p>Pour faire le ménage, j’utiliserai les commandes suivantes :</p>
<pre><code># Suppression locale (sur l’ordinateur)
git branch -d 12/1 245/1
# Suppression distante (sur mon dépôt GitHub)
git push karlcow --delete 12/1
git push karlcow --delete 245/1
</code></pre>
<p>Otsukare !</p>
<p><em>Merci Karl d’avoir permis cette traduction !</em>
<style>
pre { white-space: pre;}
</style></p>