Contribuer à EmDash : le dépôt, les conventions et la première contribution

Contribuer à un projet open source suit toujours le même cycle : on lit le dépôt, on ouvre ou on reprend une issue, on travaille sur une branche de son fork, on propose une pull request. Pour EmDash, l’essentiel du travail préparatoire consiste à distinguer deux installations très différentes — installer le CMS pour publier, et installer le projet pour le modifier. Cet article décrit le chemin, et dit à chaque étape où lire l’information à la source plutôt que de la recopier ici.

Une précision de méthode avant tout le reste. Ce site est indépendant du projet EmDash et de Cloudflare. Sur un logiciel jeune, une consigne recopiée vieillit plus vite qu’elle ne se corrige : nous indiquons donc quels fichiers du dépôt font autorité, et nous vous demandons de les ouvrir au moment où vous contribuez.

Le dépôt, et ce qu’on lit avant d’écrire une ligne

Le code d’EmDash est public et se développe sur GitHub. Récupérez l’adresse exacte depuis le site officiel du projet ou depuis les métadonnées du paquet publié, jamais depuis un article ou un forum : les dépôts miroirs et les forks abandonnés sont la première cause de contribution perdue.

Une fois sur le dépôt, quatre choses se lisent dans l’ordre, avant toute installation.

Le fichier de contribution, généralement nommé CONTRIBUTING.md à la racine ou dans .github/. C’est le document qui fait foi sur les conventions de branche, de message de commit et de test.
Le code de conduite, qui engage tous les échanges, y compris les commentaires d’issue.
La licence, qui détermine ce que vous cédez en proposant du code.
Les issues ouvertes, filtrées sur les étiquettes d’entrée : les projets marquent souvent les tickets accessibles par un libellé du type « good first issue » ou « help wanted ».

Regardez aussi la date de la dernière fusion et le rythme des pull requests ouvertes. Un projet qui fusionne chaque semaine se contribue autrement qu’un projet à l’arrêt : dans le premier cas, une branche vieille de trois semaines diverge déjà.

Si vous découvrez le projet, notre présentation générale d’EmDash situe l’architecture et le vocabulaire employés dans les issues.

Installer pour développer n’est pas installer pour publier

C’est la confusion qui fait perdre le plus de temps. Installer EmDash consiste à créer un site à partir du paquet publié et à le déployer. Installer le projet EmDash consiste à cloner le dépôt source pour en modifier le code, le construire et le tester en local.

Le second chemin suit une séquence stable d’un projet TypeScript à l’autre.

Créez votre fork sur GitHub, puis clonez votre fork — pas le dépôt d’origine.
Identifiez le gestionnaire de paquets attendu. Le fichier de verrouillage tranche : pnpm-lock.yaml, package-lock.json ou bun.lockb désignent respectivement pnpm, npm et Bun. Utiliser un autre outil réécrit le verrou et pollue votre pull request.
Vérifiez la version de Node exigée, indiquée dans le champ engines du package.json ou dans un fichier .nvmrc.
Installez les dépendances, puis lisez la section scripts du package.json : elle contient les commandes réelles de développement, de construction et de test.
Lancez la suite de tests avant toute modification. Une suite déjà rouge sur votre machine signale un problème d’environnement, et vous évite d’attribuer plus tard votre échec à votre patch.

Deux particularités tiennent à la cible d’exécution. EmDash vise un environnement serverless, ce qui suppose un runtime local fourni par l’outillage Cloudflare plutôt qu’un simple serveur Node. Et le dépôt étant organisé en plusieurs paquets, les commandes se lancent parfois à la racine, parfois dans le sous-dossier concerné : la documentation du dépôt le précise, l’arborescence seule ne suffit pas à le deviner.

Les conventions, et pourquoi nous ne les recopions pas

Les conventions d’un projet vivant changent sans préavis. Voici ce qu’il faut aller vérifier, et ce que cela implique concrètement pour votre première contribution.

À vérifier dans le dépôt	Où c’est écrit	Ce que ça change pour vous
Format des messages de commit	fichier de contribution, historique récent	un intitulé hors format peut bloquer la fusion
Branche de destination	fichier de contribution, branche par défaut	une PR ouverte sur la mauvaise branche se referme
Formatage et lint	scripts du `package.json`, configuration à la racine	l’intégration continue échoue sur un espace
Tests exigés	fichier de contribution, dossier de tests	une correction sans test de régression est souvent refusée
Accord de contribution	robot sur la première PR, fichier dédié	signature à faire une fois, sinon la PR reste bloquée

Ce dernier point mérite une explication. Les projets soutenus par une entreprise demandent fréquemment soit un certificat d’origine — une ligne signée ajoutée au commit — soit un accord de contribution à accepter une seule fois. Un robot vous le rappelle automatiquement à l’ouverture de votre première pull request. Ce n’est ni un refus ni une formalité négociable : tant que ce n’est pas fait, personne ne relira votre code.

Le cycle : issue, branche, pull request

Le chemin le plus sûr commence par une issue, y compris quand vous savez déjà corriger le problème.

Ouvrez ou commentez une issue avant de coder. Cela évite le scénario le plus décourageant de l’open source : trois soirées de travail sur un comportement que l’équipe s’apprêtait à supprimer. Un commentaire d’une ligne annonçant votre intention suffit.

Travaillez sur une branche dédiée, jamais sur la branche principale de votre fork. Une branche par sujet, un sujet par pull request. Une PR qui corrige un bogue et reformate deux cents lignes au passage devient impossible à relire, donc impossible à fusionner.

Décrivez la PR en trois blocs : ce que le code faisait, ce qu’il fait maintenant, comment vérifier. Ajoutez le numéro de l’issue liée. Si le changement touche l’interface, une capture d’écran fait gagner un aller-retour.

Attendez, puis relancez poliment. Sur un projet actif, une relecture prend souvent plusieurs jours. Les demandes de modification portent sur le code, pas sur vous : y répondre par des commits supplémentaires sur la même branche est la façon normale de procéder.

Cinq contributions utiles sans toucher au cœur

La contribution la plus utile n’est pas forcément du TypeScript. Pour un francophone, plusieurs portes d’entrée demandent surtout de la rigueur.

Contribution	Ce qu’elle demande	Où elle atterrit
Rapport de bogue reproductible	méthode, patience	une issue étayée
Correction de documentation	lecture attentive	une PR sur les fichiers de docs
Traduction de la documentation	français soigné, régularité	dépend du dispositif du projet
Exemple ou projet de démonstration	savoir faire tourner le CMS	un dépôt d’exemples ou une PR
Triage des issues existantes	reproduire, questionner, classer	des commentaires d’issue

La traduction mérite une réserve. Un projet n’accepte des traductions que s’il a prévu comment les maintenir. Sans dispositif d’internationalisation, une documentation traduite devient fausse à la première évolution, et l’équipe le sait. Demandez dans une issue avant de traduire quoi que ce soit.

Écrire un plugin est une autre forme de contribution, indirecte mais réelle, puisqu’elle éprouve les interfaces publiques. Ses limites techniques sont détaillées dans notre article sur les limites du bac à sable des plugins, à lire avant de vous lancer.

Un bon rapport de bogue est déjà une contribution

Un rapport reproductible vaut mieux qu’un correctif approximatif. Il en faut peu pour qu’il soit exploitable.

Décrivez le comportement attendu et le comportement observé, séparément. Donnez la version exacte utilisée et l’environnement : local ou déployé, système, version de Node. Fournissez la suite d’étapes minimale qui déclenche le problème — minimale au sens strict, chaque étape retirée est une hypothèse écartée. Joignez les messages d’erreur complets, en texte, pas en capture partielle.

Vérifiez enfin que le bogue n’est pas déjà signalé. Une recherche dans les issues fermées, pas seulement ouvertes, évite de rouvrir un sujet tranché.

Cette rigueur est exactement ce que la communauté attend d’un relais francophone : nous détaillons ses canaux et son fonctionnement dans notre article sur la communauté EmDash. Contribuer commence là, bien avant la première ligne de code.