Créer un projet open-source sur GitHub, de manière incrémentale

Juliette Audema
Juliette Audema2 nov. 2020
Créer un projet open-source sur GitHub


L'idée (début septembre)

Après avoir discuté avec des développeurs juniors à la recherche de leur premier emploi, j'ai décidé de rassembler des ressources pour les développeurs Ruby On Rails. Je voulais regrouper les sites web, les articles, tout ce qui pouvait aider les développeurs à trouver un emploi, préparer un entretien, trouver une communauté en ligne, évoluer dans leur carrière...

Première livraison (14 septembre)

Mon plan initial était de faire une seule page ReadMe. Il existe de nombreux dépôts de ce type sur GitHub (avec des milliers d'étoiles) et cela semblait être une solution assez décente. Comme elle serait publique, n'importe qui pourrait faire une Pull Request pour l'améliorer.
J'ai organisé les liens sur la page par catégories, il y avait même un résumé avec des ancres menant à des titres sur la page. J'ai obtenu ma première étoile et je pensais avoir pris un bon départ !

Mise à jour du projet : init Docusaurus (18 septembre)

J'ai regardé tous les projets comme celui que j'avais en tête dans mes dépôts étoilés pour m'inspirer et j'ai trouvé The Tech Interview Handbook. Il avait un beau site web. En le parcourant, j'ai vu référentiels Docusaurus et j'ai décidé de l'ajouter à mon projet.

 Docusaurus

En gros, Docusaurus vous donne un modèle pour votre documentation open sourced. Il est construit en utilisant React et les pages sont au format markdown. Ce qui est bien pour moi, c'est que vous pouvez avoir un lien vers "Edit this page" sur chaque page de doc pour ouvrir directement une Pull Request si vous voulez faire un changement.
J'aurais pu opter pour quelque chose d'autre comme just-the-docs mais, hé, j'ai vu Docusaurus en premier.

Mise à jour vers Docusaurus v2 et commencer à écrire (26 septembre)

J'ai fait le changement vers la v2 parce que je trouvais que le modèle était plus joli et qu'il avait aussi un mode sombre/clair, ce que tout le monde semble aimer. Avant le lancement officiel, je voulais écrire quelques pages de documentation. Je ne voulais pas que les gens aillent sur le site et le trouvent vide, je voulais leur donner un avant-goût de ce qu'il pourrait être.

Premier déploiement ! (4 octobre)

Ce qui est également génial avec Docusaurus, c'est que vous pouvez le déployer en utilisant les pages GitHub, et tada, vous êtes en direct !

Avant de déployer le site, j'ai rempli le ReadMe avec tous les détails techniques, je me suis concentré sur la façon d'ajouter du contenu (l'anatomie d'un fichier markdown dans Docusaurus) et je n'ai pas fait beaucoup d'efforts pour décrire comment contribuer au dépôt.

9 octobre : rédaction des premiers numéros

À cette époque, je lisais des articles sur la Hacktoberfest et sur la façon de contribuer à l'open source. L'un des points soulevés était que si je pensais à quelque chose qui pourrait être facilement codé, je devrais m'abstenir de le faire moi-même et je devrais plutôt écrire des numéros pour permettre aux autres développeurs de contribuer. J'ai donc écrit plusieurs problèmes étiquetés "bon premier problème" pour que d'autres développeurs puissent s'en emparer.

Le premier contributeur est arrivé ! (11 octobre)

Pour être transparent, le premier contributeur est l'amie qui a démarré le dépôt depuis le début. Elle a spontanément écrit sur l'un des problèmes qu'elle était prête à le faire. En quelques jours, elle a proposé une solution intéressante et a obtenu la fusion de sa première Pull Request sur le projet.

Mise en place effective de mon repo pour l'open-source (15 octobre)

On pourrait penser que mon projet était déjà open-source à ce moment-là puisque le code était public et que quelqu'un y contribuait.


Grâce à l'excellente documentation sur l'open source par GitHub, j'ai réalisé que certaines documentations manquaient :
- une licence
- un fichier de contribution
- un code de conduite
- une mise à jour du ReadMe

J'ai choisi ma licence grâce au site "choose a licence" qui m'a facilité la tâche en expliquant clairement les différentes licences existantes.

J'ai déplacé presque tout ce que j'avais d'abord mis dans le ReadMe vers le fichier de contribution. Il m'a fallu beaucoup de temps pour décrire les processus d'une Pull Request ou les aspects techniques du projet. Je m'en suis remercié plus tard en écrivant un problème ou en répondant à un commentaire avec des liens vers les parties pertinentes du fichier.

J'ai choisi un code de conduite existant au lieu d'écrire le mien pour gagner du temps. J'ai choisi le Contributor Covenant Code of Conduct parce que la communauté Rails l'utilise.

J'ai finalement dû réécrire le ReadMe. J'ai ajouté l'objet du projet, les objectifs et les liens vers les documents décrits ci-dessus.


J'ai même créé des modèles pour les nouveaux problèmes ou les nouvelles demandes de révision. Maintenant, chaque fois que quelqu'un crée l'une de ces demandes, il dispose de directives pour l'aider à les remplir.

Enfin, j'ai décidé de mettre les pages qui restent à écrire comme projets dans le repo. J'ai créé un projet pour chaque section du site, comme par exemple : "Comment trouver un emploi", "Comment s'entraîner", "Comment s'inspirer"... Les projets sont organisés en kaban avec trois colonnes : " À faire ", " En cours ", " Fait ".
Chaque carte représente une page à écrire, avec des listes de choses à faire pour les sujets à aborder dans la page :

Chaque carte représente une page à écrire

Page Kaban pour la page des ressources sur la façon de trouver un emploi

Un deuxième contributeur ! (19 octobre)
🎉


Ajout de quelques bots sympas et de protections de branches (21 octobre)

Parce que quel est l'intérêt d'être un développeur web si on ne peut pas faire des choses pour le plaisir ?
J'ai ajouté la mention "tous les contributeurs" pour mettre en évidence les contributions faites. Vous avez peut-être déjà vu certains d'entre eux au bas des dépôts :

mettre en évidence les contributions apportées

Section "Contributeurs" du ReadMe

J'ai également ajouté les premières contributions pour accueillir les contributeurs lorsqu'ils font leurs premières pull requests ou leurs premiers problèmes.
Le 21 octobre est aussi le jour où j'ai accidentellement supprimé la branche gh-pages utilisée pour construire et déployer le site en tant que page GitHub... Quelqu'un m'a gentiment signalé que le site retournait la chose la plus redoutée : une erreur 404. Après avoir restauré la branche, j'ai défini une règle pour que cela ne se reproduise pas aussi facilement (j'ai fait de même pour la branche principale, juste au cas où).

Réflexion sur ce qui va suivre (fin octobre, début novembre)

Je pense actuellement à ajouter un CI/CD pour au moins déployer automatiquement les branches fusionnées (si je suis fantaisiste, j'ajouterai un linter).
J'ai hâte de voir le lancement de la fonctionnalité Discussions sur le repo GitHub. Pour l'instant les discussions se font sur les issues mais elles sont vite encombrées.

Mon point de vue

Vous apprenez BEAUCOUP en mettant en place un projet pour l'open source. Vous devez apprendre à configurer un dépôt pour plusieurs contributeurs. Si vous prenez le temps d'écrire de la documentation, vous déciderez du flux de travail que vous souhaitez pour votre dépôt. Vous prendrez des décisions conscientes et définirez ce que vous attendez d'un problème ou d'une demande de reprise.

Plus vous écrirez sur votre projet, plus il y aura de personnes qui pourront vous rejoindre et vous aider. C'est cool de savoir comment faire quelque chose, mais l'expliquer à un lecteur potentiel, c'est autre chose ! Grâce aux questions de vos contributeurs, vous pourrez également améliorer votre projet au fil du temps.


Comme l'a dit Richard Schneeman:

"Cela fait du bien de reconnaître que cette chose simple que vous faites est en fait une tâche difficile que vous avez maîtrisée. C'est aussi une profonde leçon d'humilité qui me force à m'efforcer continuellement d'écrire de meilleurs outils, documents et articles de blog."

Dans de nombreux articles sur la création d'un projet open-source, on vous dit qu'il faut être patient pour trouver des contributeurs. J'ai eu la chance d'avoir déjà une communauté active de développeurs Ruby On Rails grâce au meet-up que j'anime actuellement.
Mais je n'ai pas non plus hésité à demander de l'aide si je pensais que quelqu'un serait parfait pour réviser un PR spécifique ou simplement pour encourager les gens à contribuer. Le fait d'exposer les problèmes au grand jour est également un bon moyen d'inciter les gens à participer.

Enfin, le fait d'avoir un projet open source change de perspective. Le but n'est pas d'écrire du code et d'en tirer le plus possible, mais de donner les moyens à d'autres personnes d'écrire du code. Votre succès ne se mesure pas à l'avancée de votre projet par votre seule volonté, mais au nombre de personnes qui peuvent vous rejoindre, se sentir en sécurité et contribuer. Vous aidez les gens à vous aider. C'est mon genre de confiture.

Partager
Juliette Audema
Juliette Audema2 nov. 2020

Blog de Capsens

Capsens est une agence spécialisée dans le développement de solutions fintech. Nous aimons les startups, la méthodologie scrum, le Ruby et le React.