Un site communautaire avec Eleventy: Se préparer aux contributions

Online Coding Courses for Kids

Je me suis récemment retrouvé à atteindre Onze (aka 11ty) au-dessus de tous les autres outils lorsque je souhaite développer un site Web. Il est difficile de battre un générateur de site statique qui offre des opportunités avancées de création de modèles tout en vous écartant et en vous permettant de simplement créer.

L’un de ces sites est Stade de style, une vitrine CSS moderne conçue par les contributions de la communauté. Eleventy était parfait pour ce projet communautaire de plusieurs manières:

  • Sa construction exceptionnellement rapide localement et sur un hôte de production
  • Il n’a pas d’opinion sur la façon de créer des modèles
  • Sa capacité à créer n’importe quel type de fichier avec un contrôle complet sur comment et où les fichiers sont rendus
  • Sa capacité à mélanger des langages de modèles, tels que HTML, Markdown et Nunjucks
  • Il est très performant car il se compile en HTML statique sans dépendances requises pour la production

La principale raison pour laquelle Eleventy est un excellent choix pour créer un site axé sur la communauté est la possibilité de créer dynamiquement des pages de site à partir de sources de données. Nous verrons comment utiliser cette fonctionnalité et plus encore lorsque nous créerons notre exemple de site communautaire.

Que faut-il pour créer un site axé sur la communauté?

Dans un passé pas si lointain, la création d’un site axé sur la communauté pouvait être un processus douloureux impliquant des cauchemars CMS essayant de créer des flux de travail de contributeurs. Armé d’Eleventy et de quelques autres outils modernes, il est désormais presque entièrement automatisable avec un minimum de supervision.

Avant de commencer à inviter des contributeurs, nous avons du travail à faire nous-mêmes.

1. Déterminez le contenu auquel les contributeurs auront accès pour modifier

Cela guidera de nombreuses autres décisions. Dans le cas de l’utilisation d’Eleventy pour Style Stage, j’ai créé un fichier JSON que les contributeurs peuvent utiliser pour créer des pull requests pour modifier et fournir leurs propres métadonnées pertinentes utilisées pour créer leurs pages.

Une première version du fichier JSON qui avait initialement un «exemple» pour les contributeurs à référencer. Cette capture d'écran montre également les détails des deux premiers contributeurs.

Peut-être souhaitez-vous également autoriser l’accès pour inclure des actifs supplémentaires, ou peut-être qu’il est judicieux d’avoir plusieurs fichiers de données pour faciliter la catégorisation et l’interrogation des données. Ou peut-être que les contributeurs peuvent ajouter des fichiers Markdown dans un répertoire particulier.

Considérez la portée de ce que les contributeurs peuvent modifier ou soumettre, et comparez cela à une estimation de votre disponibilité pour examiner les soumissions. Cela aidera à créer une communauté réussie et gérable.

Actions GitHub peut permettre de étiquette ou fermez une demande d’extraction avec des fichiers non valides si vous avez besoin d’un filtrage automatisé avancé du contenu entrant.

2. Créer des directives pour les contributeurs

Passer du temps à réfléchir à vos directives peut vous aider à élaborer votre plan global. Vous pouvez identifier des fonctionnalités supplémentaires nécessaires, ou des éléments qui peuvent être automatisés.

Une fois vos consignes préparées, il est préférable de les inclure dans un fichier spécial de votre référentiel GitHub appelé CONTRIBUTING.md. Le nom de fichier en majuscules est le format attendu. Le fait de disposer de ce fichier crée un lien supplémentaire automatique pour les contributeurs lorsqu’ils créent leur pull request ou leurs problèmes dans une invite leur demandant de s’assurer qu’ils ont lu les consignes:

Capture d’écran fournie par le Documentation GitHub.

Comment gérer les licences de contenu et l’attribution des auteurs font partie de cette catégorie. Par exemple, Style Stage publie les feuilles de style contribuées sous le Licence CC BY-NC-SA mais les auteurs conservent les droits d’auteur sur les graphiques originaux. Dans le cadre du processus de création, la licence et l’attribution de l’auteur sont ajoutées aux styles, et les métadonnées d’attribution des auteurs sont mises à jour dans le modèle de page de style.

Vous voudrez également prendre en compte les règles relatives au contenu acceptable et à ce qui entraînerait le rejet des soumissions. Style Stage indique que:

Les soumissions seront rejetées pour utilisation d’images obscènes, excessivement violentes ou autrement désagréables, enfreignant les directives ci-dessus, ou pour d’autres raisons à la discrétion du responsable.

3. Préparer le workflow et les automatisations

Alors qu’Eleventy s’occupe de la construction du site, les autres acteurs clés permettant les contributions de Style Stage sont Netlify et GitHub.

Les contributeurs soumettent une demande d’extraction au dépôt Style Stage sur GitHub et, lorsqu’ils le font, Netlify crée un aperçu de déploiement. Cela permet aux contributeurs de vérifier que leur soumission fonctionne comme prévu et me fait gagner du temps en tant que responsable de la maintenance en n’ayant pas à retirer les soumissions pour m’assurer qu’elles respectent les directives.

Le statut des mises à jour de déploiement de Netlify en temps réel sur la page de révision de la demande d’extraction. Une fois que le dernier élément (“/ deploy-preview”) affiche “Deploy preview ready!” cliquer sur “Détails” lancera le lien en direct vers l’aperçu.

Toutes les discussions ont lieu via GitHub. Cela présente l’avantage supplémentaire de la responsabilité publique qui aide à dissuader les mauvais acteurs.

Si le contributeur doit apporter une modification, il peut mettre à jour sa pull request ou demander un redéploiement de l’aperçu de la branche s’il s’agit d’un élément distant qui a changé. Ce redéploiement est une très petite étape manuelle, et il peut ne pas être nécessaire pour chaque PR – ou même pas du tout, selon la façon dont vous acceptez les contributions.

La dernière étape est l’approbation finale du PR et la fusion dans la branche principale. Une fois la demande d’extraction fusionnée, Netlify déploie immédiatement les modifications en production.

Eleventy est, bien sûr, un générateur de site statique, et plusieurs hébergeurs proposent des webhooks pour déclencher une compilation. Plugins de compilation de Netlify en sont un bon exemple. Mais si vous devez actualiser les données plus souvent qu’à chaque fois qu’un PR est fusionné, une option consiste à utiliser IFTTT ou Zapier pour configurer des déploiements quotidiens ou des déploiements en fonction de divers autres déclencheurs.

Exemple de configuration terminée d’un déploiement quotidien via webhook à partir de IFTTT

Il convient de noter que ce dont nous parlons ici limite votre audience de contributeurs à avoir un compte GitHub. Cependant, les contributions GitHub peuvent être effectuées entièrement via l’interface Web, il est donc très possible de fournir des conseils afin que d’autres utilisateurs, même ceux qui ne codent pas, puissent toujours participer.

4. Choisissez une méthode pour les mises à jour des contributeurs et de la communauté

La première considération ici est de décider à quel point il est essentiel pour les contributeurs de connaître les mises à jour de votre site en évaluant l’impact probable du changement.

Dans le cas de Style Stage, le noyau restera inchangé, mais certaines fonctionnalités optionnelles sont prévues. Je suis allé avec une newsletter hebdomadaire (-ish). De cette façon, c’est quelque chose que les gens peuvent choisir et il y a de la valeur pour les contributeurs et les utilisateurs.

“Utiliser les formulaires Netlify et les fonctions Netlify pour créer un widget d’inscription aux e-mails” de Matthew Ström est un excellent endroit pour apprendre à ajouter des abonnés à votre newsletter avec un formulaire statique dans Eleventy. Il couvre également une fonction permettant d’envoyer l’e-mail de l’abonné à Buttondown, un service de messagerie léger. Pour un exemple de gestion de votre modèle d’e-mail et de votre contenu Buttondown dans Eleventy, revoir la configuration de la scène de style qui montre comment exclure la newsletter de la construction du site publié.

Si vous n’attendez que des mises à jour de faible priorité, les notifications de dépôt de GitHub peuvent être suffisantes pour la communication. La création de versions est une autre façon de procéder. Ou, hé, il est même possible d’incorporer des notifications sur le site lui-même.

5. Trouvez et interagissez avec des contributeurs potentiels

Style Stage était une idée que j’ai approuvée en lançant un sondage sur Twitter. J’ai ensuite lancé un «appel à contributeurs» et j’ai contacté les répondants ainsi que ceux qui m’ont retweeté. Un court calendrier a également aidé à trouver des contributeurs motivés qui ont aidé Style Stage à éviter de se lancer sans aucune soumission. Beaucoup de ces contributeurs sont devenus des évangélistes qui ont présenté Style Stage à encore plus de gens. J’ai également fait la promotion d’un livestream de lancement qui faisait également office de matériel promotionnel.

C’est ce que signifie «s’engager» avec les contributeurs. Créer des avenues d’engagement et rester engagé avec eux aide à transformer les contributeurs occasionnels en «fans» qui encouragent les autres à participer.

N’oubliez pas que le contenu du site est un excellent endroit pour encourager la participation! Stade de style consacre toute sa page à encourager les soumissions. Si cela n’est pas possible pour vous, vous pouvez envisager d’utiliser des invites de contribution là où cela a du sens.

6. Finaliser les paramètres du dépôt et inclure les fichiers de santé communautaire

Enfin, assurez-vous que votre référentiel est publié publiquement et qu’il inclut les fichiers de «santé communautaire» applicables. Il s’agit de documents qui aident à établir des lignes directrices, à définir de bonnes attentes avec les membres de la communauté, à définir un code de conduite et d’autres informations qui contribuent à la «santé» globale de la communauté. Il y a un tas de exemples, suggestions et astuces sur la façon de faire cela dans la documentation GitHub.

Bien qu’il y ait une demi-douzaine de fichiers mentionnés dans la documentation, d’après mon expérience jusqu’à présent, les trois fichiers dont vous aurez besoin au minimum sont:

  • une README.md fichier à la racine du projet qui comprend le nom du projet et une bonne description de ce qu’il est. GitHub affichera le contenu sous la liste des fichiers dans le dépôt.
  • une CONTRIBUTING.md fichier décrivant le processus de soumission des contributions. Soyez explicite en ce qui concerne les étapes impliquées et ce qui constitue une «bonne» soumission.
  • un modèle de demande d’extraction. Je ne dirais pas exactement que c’est une chose obligatoire, mais cela vaut la peine d’être ajouté à cette liste car cela renforce encore les attentes en matière de soumission de contributions. De nombreux modèles comprendront même une liste de contrôle qui détaille les exigences d’approbation.

Oh, et avoir une règle de protection de branche sur la branche principale est une autre bonne idée. Vous pouvez le faire en allant à SettingsBranches depuis le dépôt et en sélectionnant l’option «Ajouter une règle». «Exiger des révisions des demandes d’extraction avant la fusion» et «Exiger un examen des propriétaires de code» sont les deux paramètres clés à activer. Vous pouvez consulter la documentation GitHub pour en savoir plus sur cette protection.

À suivre…

Ce que nous avons couvert ici est un point de départ pour créer un site communautaire avec Eleventy. Le fait est qu’il y a plusieurs choses à considérer avant de passer directement au code. Les communautés ont besoin de soins et cela nécessite quelques étapes qui aident à établir une communauté engagée et saine.

Vous avez probablement hâte de commencer à coder un site communautaire avec Eleventy! Eh bien, cela se produira dans la prochaine tranche de ces deux parties. Ensemble, nous allons développer un démarreur Eleventy à partir de zéro que vous pouvez étendre pour votre propre site communautaire (ou personnel).

Close Menu