A propos

QuietCMS est un projet libre, ouvert et communautaire. Chaque ligne de code, chaque correction de documentation et chaque suggestion de fonctionnalité contribuent à le rendre plus robuste, plus accessible et plus agréable à utiliser. Que vous soyez développeur chevronné, rédacteur, traducteur, designer ou simple utilisateur curieux, il existe une manière de participer qui correspond à vos compétences et au temps dont vous disposez. Ce guide détaille l'ensemble du processus de contribution, des premiers pas jusqu'à l'intégration de votre travail dans le projet.

Pourquoi contribuer ?

Contribuer à un logiciel open-source comme QuietCMS présente de nombreux avantages, bien au-delà de la simple satisfaction d'aider un projet que l'on apprécie. C'est l'occasion d'améliorer concrètement vos compétences techniques en travaillant sur une base de code réelle, lue et utilisée par d'autres. C'est aussi un excellent moyen de comprendre en profondeur le fonctionnement interne d'un système de gestion de contenu : routage, gestion des fichiers, sécurité, génération de pages, mise en cache. Enfin, contribuer permet de rejoindre une communauté de personnes partageant les mêmes centres d'intérêt et les mêmes valeurs de sobriété logicielle.

La philosophie de QuietCMS repose sur trois piliers : zéro dépendance externe, légèreté et sécurité. Chaque contribution est évaluée à l'aune de ces principes. Un correctif qui alourdirait inutilement le projet, introduirait une bibliothèque tierce ou affaiblirait la posture de sécurité ne sera pas retenu, même s'il fonctionne. Garder ces trois valeurs en tête vous fera gagner un temps précieux et augmentera considérablement les chances que votre travail soit intégré. Pour bien comprendre l'esprit du projet, n'hésitez pas à parcourir la page À propos de QuietCMS avant de vous lancer.

Code de conduite

Toute contribution doit s'inscrire dans un esprit de respect mutuel et de constructivité. Les échanges, qu'ils aient lieu dans une issue, une pull request ou une discussion, doivent rester professionnels, bienveillants et orientés vers l'amélioration du projet. Nous accordons une grande importance à un environnement accueillant pour les nouveaux venus : personne ne devrait avoir peur de poser une question jugée « basique » ou de soumettre une première contribution imparfaite. Les comportements irrespectueux, condescendants ou discriminatoires ne seront pas tolérés, quelle que soit la qualité technique des contributions associées.

Concrètement, cela signifie que l'on critique le code, jamais la personne. Lorsqu'une proposition n'est pas retenue, l'explication doit être factuelle et argumentée. Lorsqu'on demande une modification, on explique pourquoi. Et lorsqu'on reçoit une critique, on la considère comme une opportunité d'apprendre plutôt que comme une attaque personnelle.

Les différentes façons de contribuer

Une idée reçue tenace voudrait que contribuer à un projet open-source se résume à écrire du code. C'est faux. Une documentation claire, une traduction soignée ou un rapport de bug bien rédigé ont souvent autant de valeur qu'un correctif. Voici les principales formes que peut prendre votre participation :

• Signaler des bugs en décrivant précisément le problème et les conditions de reproduction.
• Proposer des fonctionnalités qui s'inscrivent dans la philosophie du projet.
• Écrire du code pour corriger des anomalies ou implémenter de nouvelles capacités.
• Améliorer la documentation, qu'il s'agisse de corriger une coquille ou de rédiger un guide entier.
• Traduire l'interface dans de nouvelles langues pour rendre QuietCMS accessible au plus grand nombre.
• Concevoir des thèmes qui élargissent les possibilités graphiques offertes aux utilisateurs.
• Développer des plugins qui ajoutent des fonctionnalités optionnelles sans alourdir le cœur.

Signaler un bug efficacement

Un bon rapport de bug fait gagner un temps considérable aux mainteneurs et accélère la résolution du problème. Avant d'ouvrir une nouvelle issue, prenez toujours le temps de vérifier que le problème n'a pas déjà été signalé : parcourez les issues ouvertes et fermées à l'aide de quelques mots-clés. Si une issue similaire existe, ajoutez-y vos propres informations plutôt que d'en créer une nouvelle ; cela évite la dispersion des discussions.

Si le problème n'a pas encore été remonté, ouvrez une issue en incluant systématiquement :

• La version de PHP utilisée (php --version) ;
• Le serveur web et sa version (Apache 2.4, Nginx 1.24…) ;
• Le système d'exploitation et son environnement ;
• Les étapes précises et numérotées pour reproduire le bug ;
• Le comportement observé et le comportement attendu ;
• Les messages d'erreur ou extraits de logs pertinents.

Plus votre rapport est précis, plus il est facile de reproduire le problème — et un bug que l'on peut reproduire est un bug à moitié résolu. Joindre une capture d'écran ou un court enregistrement peut également lever bien des ambiguïtés lorsque le défaut est de nature visuelle.

Proposer une fonctionnalité

Les demandes de fonctionnalités sont examinées au regard de la philosophie du projet : zéro dépendance externe, légèreté et sécurité. Ouvrez une issue avec le label enhancement en décrivant le besoin concret, le cas d'usage réel et la valeur ajoutée pour les utilisateurs. Évitez de décrire directement une solution technique : exposez d'abord le problème que vous cherchez à résoudre. Cette approche, parfois résumée par la formule « le pourquoi avant le comment », laisse la place à une discussion ouverte sur la meilleure manière d'y répondre.

Gardez à l'esprit qu'une fonctionnalité refusée n'est pas un échec. Beaucoup d'idées excellentes en elles-mêmes ne trouvent pas leur place dans le cœur du CMS parce qu'elles s'adressent à une minorité d'utilisateurs ou qu'elles peuvent être implémentées sous forme de plugin. C'est précisément le rôle du système d'extensions : permettre d'ajouter des capacités spécifiques sans alourdir l'expérience par défaut de tout le monde.

Configurer l'environnement de développement

L'un des grands avantages de QuietCMS est qu'aucun outil de build n'est nécessaire. Pas de Node.js à installer, pas de compilateur d'assets, pas de gestionnaire de dépendances. Clonez simplement le dépôt et lancez le serveur intégré de PHP :

git clone https://github.com/quietcms/quietcms.git
cd quietcms/cms
php -S localhost:8000

Accédez ensuite à http://localhost:8000/install.php pour initialiser votre environnement local. En quelques secondes, vous disposez d'une installation complète et fonctionnelle, prête à recevoir vos modifications. Le guide d'installation détaille les prérequis serveur et les options de configuration si vous souhaitez tester QuietCMS dans des conditions plus proches de la production.

Comprendre l'architecture du projet

Avant de modifier le code, il est utile de se familiariser avec l'organisation générale du projet. QuietCMS repose sur une architecture volontairement simple. Toutes les données — pages, articles, catégories, médias et paramètres — sont stockées sous forme de fichiers JSON sur le système de fichiers, ce qui élimine le besoin d'une base de données relationnelle. Un routeur léger interprète les URL et les associe au bon gabarit, tandis que des gestionnaires dédiés se chargent du contenu, des thèmes, des plugins et de la sécurité.

Cette séparation claire des responsabilités facilite l'exploration du code : chaque grande fonction du CMS correspond à un fichier identifiable. Si vous découvrez le projet, la documentation technique constitue le meilleur point d'entrée pour comprendre comment ces pièces s'assemblent et où intervenir selon le type de modification envisagée.

Le flux de contribution au code

Lorsque vous êtes prêt à soumettre une modification, le processus suit toujours les mêmes étapes. Cette régularité n'est pas une contrainte bureaucratique : elle garantit que chaque changement est traçable, relisible et réversible.

Concrètement, pour soumettre une modification :

• Forkez le dépôt et créez une branche dédiée depuis main, au nom explicite (par exemple fix/og-image-path ou feat/pagination-categories) ;
• Réalisez vos modifications par petits incréments cohérents plutôt qu'en un seul commit monolithique ;
• Rédigez des messages de commit suivant la convention Conventional Commits : fix:, feat:, docs:, refactor:… ;
• Assurez-vous que la fonctionnalité est testée manuellement et ne provoque aucune régression sur les cas existants ;
• Ouvrez la pull request avec une description claire du problème résolu ou de la fonctionnalité ajoutée, en liant l'issue correspondante le cas échéant.

Conventions de commit

Les messages de commit ne sont pas une formalité : ils racontent l'histoire du projet. Un historique clair permet de comprendre, des mois plus tard, pourquoi une décision a été prise. La convention Conventional Commits structure chaque message autour d'un préfixe qui indique la nature du changement. feat: introduit une nouvelle fonctionnalité, fix: corrige une anomalie, docs: ne touche qu'à la documentation, refactor: réorganise le code sans modifier son comportement, et style: concerne le formatage. Cette discipline permet, à terme, de générer automatiquement des notes de version cohérentes.

Style et standards de code

Pour préserver la cohérence et la lisibilité de la base de code, QuietCMS suit un ensemble de règles strictes que toute contribution doit respecter :

• Tous les fichiers PHP commencent par declare(strict_types=1); afin de bénéficier du typage strict ;
• Le code respecte les conventions PSR-1 et PSR-12 pour le nommage et la structure ;
• Toute donnée affichée dans le HTML doit impérativement être échappée avec htmlspecialchars() pour prévenir les failles XSS ;
• Aucune dépendance externe (Composer ou autre) ne doit être introduite — le projet doit rester totalement autonome ;
• Les nouveaux fichiers JSON doivent respecter le schéma de leur type, décrit dans la documentation ;
• Le code doit être commenté là où l'intention n'est pas évidente, en français, de manière concise.

Ces règles peuvent sembler contraignantes au premier abord, mais elles sont la garantie qu'un fichier écrit par un contributeur aujourd'hui restera compréhensible par un autre demain. La sécurité, en particulier, n'est jamais négociable : une fonctionnalité brillante mais vulnérable sera toujours refusée.

Améliorer la documentation

La documentation est le premier contact de la plupart des utilisateurs avec le projet. Une phrase ambiguë, un exemple obsolète ou une étape manquante peuvent décourager un nouvel arrivant. C'est pourquoi les contributions à la documentation sont particulièrement précieuses et accessibles : elles ne nécessitent pas de maîtriser PHP. Corriger une faute, clarifier une explication, ajouter un exemple concret ou traduire une section sont autant de gestes qui améliorent l'expérience de tous. Si vous remarquez quelque chose d'incompréhensible en lisant la documentation, c'est probablement que d'autres l'ont ressenti aussi : votre correction servira à beaucoup de monde.

Traduire QuietCMS

QuietCMS est conçu pour être multilingue, et son interface peut être traduite dans de nouvelles langues. Si votre langue maternelle n'est pas encore prise en charge, ou si une traduction existante vous semble perfectible, votre aide est la bienvenue. Une bonne traduction ne se contente pas de transposer mot à mot : elle adapte le ton, respecte les conventions typographiques de la langue cible et reste cohérente d'un écran à l'autre. C'est un travail d'orfèvre qui rend le logiciel véritablement accessible à des communautés entières d'utilisateurs.

Concevoir un thème

Les thèmes déterminent l'apparence des sites construits avec QuietCMS. Créer un nouveau thème est une excellente façon de contribuer si vous êtes à l'aise avec le HTML et le CSS. Un thème de qualité est responsive, accessible, sobre en ressources et respecte les bonnes pratiques d'accessibilité, notamment en matière de contraste des couleurs et de taille des zones interactives. Avant de proposer un thème, testez-le sur différents types de contenus — pages, articles, listes de catégories — et sur différentes tailles d'écran. Un thème qui obtient d'excellents scores aux audits de performance et d'accessibilité a toutes ses chances d'être mis en avant.

Développer un plugin

Le système de plugins est le mécanisme privilégié pour ajouter des fonctionnalités sans toucher au cœur du CMS. Grâce à un système de hooks et de filtres, un plugin peut intervenir à des moments clés du cycle de vie d'une page : transformer le contenu, enrichir l'en-tête, ajouter des éléments d'interface dans l'administration, etc. Cette approche modulaire est au cœur de la philosophie de légèreté du projet : tout le monde profite d'un cœur minimal et rapide, et chacun active uniquement les extensions dont il a réellement besoin. Si votre idée de fonctionnalité s'adresse à un public spécifique, un plugin est presque toujours la bonne réponse.

Tester ses modifications

Avant de soumettre une pull request, testez vos changements de manière méthodique. Vérifiez d'abord que la fonctionnalité que vous avez ajoutée ou corrigée se comporte comme prévu. Assurez-vous ensuite qu'elle n'introduit aucune régression : parcourez les pages principales du site, créez et modifiez du contenu, et confirmez que tout fonctionne comme avant. Prêtez une attention particulière aux cas limites : champs vides, caractères spéciaux, contenus très longs. Un changement qui résout un problème mais en crée un autre n'est pas un progrès.

Signaler une faille de sécurité

La sécurité occupe une place centrale dans QuietCMS, et la manière de signaler une vulnérabilité diffère de celle d'un bug ordinaire. Une faille de sécurité ne doit jamais être divulguée publiquement dans une issue ouverte, car cela exposerait tous les sites en production avant qu'un correctif ne soit disponible. La bonne pratique consiste à effectuer une divulgation responsable : signaler le problème de manière privée, laisser le temps de préparer un correctif, puis publier les détails une fois la mise à jour diffusée. Pour comprendre l'ensemble des mécanismes de protection déjà en place et la posture de sécurité du projet, consultez la rubrique Sécurité.

Après la pull request : la revue

Une fois votre pull request ouverte, elle entre dans un processus de revue. Un mainteneur examine votre code, pose éventuellement des questions et demande parfois des ajustements. Ce dialogue est une étape normale et saine : même les contributeurs les plus expérimentés voient leur travail relu et amélioré. Répondez aux commentaires avec ouverture, apportez les modifications demandées sur la même branche, et n'hésitez pas à expliquer vos choix lorsque vous pensez qu'ils sont justifiés. La revue de code est l'un des meilleurs moyens de progresser : profitez-en pour apprendre.

Reconnaissance des contributeurs

Chaque contribution compte, et le travail de chacun mérite d'être reconnu. Les personnes qui participent au projet, quelle que soit la nature ou l'ampleur de leur apport, font partie de son histoire. Une coquille corrigée, une traduction ajoutée, un bug subtil résolu : tout cela construit, pas à pas, un logiciel meilleur. En contribuant à QuietCMS, vous ne faites pas que donner de votre temps ; vous rejoignez une démarche collective qui valorise la qualité, la sobriété et l'entraide.

Pour aller plus loin

Vous êtes désormais prêt à franchir le pas. Commencez modestement : corrigez une coquille dans la documentation, signalez un bug que vous avez rencontré, ou proposez une petite amélioration. Chaque grande contribution a commencé par un premier pas. Pour approfondir le fonctionnement interne du CMS, plongez dans la documentation technique ; pour découvrir les évolutions prévues et les chantiers en cours, consultez la feuille de route. Quel que soit le chemin que vous choisirez, soyez assuré que votre participation est attendue et appréciée. Bienvenue parmi les contributeurs de QuietCMS !