Ce guide est conçu pour ceux qui souhaitent contribuer au projet open-source Discourse, détaillant la configuration et les conventions nécessaires pour une collaboration efficace.
Niveau d’utilisateur requis : Bien que tout le monde puisse contribuer au code, vous devez être familier avec Ruby et JavaScript.
Résumé
Cette documentation couvrira les points suivants :
- Configuration de votre environnement de développement
- Compréhension de là où commencer à contribuer
- Création et utilisation des plugins Discourse
- Contribution au noyau (core) de Discourse
- Conventions de codage à respecter
- Soumission de vos contributions sur GitHub
Configuration de l’environnement de développement
Avant de commencer à contribuer, assurez-vous que votre environnement de développement est correctement configuré. Suivez le guide approprié pour votre plateforme :
- Toutes les plateformes : Installer Discourse pour le développement avec Docker
- Mac OS X : Guide du débutant pour installer Discourse sur macOS pour le développement
- Linux (Ubuntu) : Guide du débutant pour installer Discourse sur Ubuntu pour le développement
- Windows : Guide du débutant pour installer Discourse sur Windows 10 pour le développement
Savoir par où commencer
Discourse est un projet vaste, et la compréhension de ses technologies sous-jacentes telles que Ruby et JavaScript est essentielle. Pour des conseils sur la façon de commencer, consultez le guide pour les débutants.
Création et utilisation des plugins
Les plugins offrent un moyen de comprendre les mécanismes internes de Discourse par petites portions et vous permettent de commencer à contribuer du code facilement. Commencez par :
- Developing Discourse Plugins - Part 1 - Create a basic plugin
- (deprecated) Plugin outlet locations theme component
Pour vous inspirer, explorez les idées populaires dans les catégories Contribute > Feature et Customization > Extras.
Contribution au noyau (core) de Discourse
Le code du noyau de Discourse est géré dans le dépôt principal sur GitHub.
Signature de la CLA
Avant de contribuer, lisez et signez le Contrat de licence de contribution aux forums électroniques Discourse. L’équipe ne peut pas accepter légalement les demandes de tirage (PR) des utilisateurs qui n’ont pas signé la CLA.
Se mettre en jambes avec des tâches de démarrage
Explorez le tag pr-welcome pour trouver de bonnes tâches pour débuter.
Parcourir la liste des bugs
Corrigez les bugs présents dans la liste des bugs ouverts triés par nombre de « J’aime ». Laissez un message si vous travaillez sur un bug ; si vous ne le terminez pas, laissez des notes pertinentes pour que quelqu’un d’autre puisse continuer votre travail.
Aider sur les sujets de fonctionnalités
Contribuez avec des détails et des maquettes aux demandes de fonctionnalités pour faciliter leur processus d’approbation. Rappelez-vous que toutes les fonctionnalités ne seront pas incluses dans le noyau.
Améliorer les performances
Nous accueillons les demandes de tirage qui améliorent les performances côté client ou serveur, en se concentrant sur les zones à fort impact comme le chargement initial de la page d’accueil ou la vue des sujets.
Améliorer les projets maintenus par Discourse
Contribuez à d’autres projets open-source maintenus par Discourse. Certains projets notables incluent :
- Logster - visualiseur de logs en interface web
- Message Bus - moteur pour les interactions en direct sur le site
- Rack Mini Profiler - outil de diagnostic
- Discourse API - consommateur d’API
- Discourse Docker - moteur de distribution de Discourse
- WP Discourse - plugin WordPress
- Memory Profiler - profileur pour Ruby
- Ember Performance - suite de tests de performance pour Ember
Conventions de codage
Le nommage est CRITIQUE
Visez une parité de 100 % entre les termes utilisés sur le site et les noms des classes et des colonnes dans la base de données (par ex., « posts »).
La compatibilité avec les dernières versions des dépendances est CRITIQUE
Assurez la compatibilité avec les dernières versions stables des bibliothèques telles que Rails, Ruby et Ember. Testez les régressions lors de la mise à jour des dépendances.
Les contributions axées uniquement sur les tests sont les bienvenues
Les contributions de tests sont les bienvenues, en particulier pour les processus et les actions de contrôleur non testés. Évitez le mock (simulation) sauf en cas de nécessité absolue.
Les contributions axées uniquement sur le refactoring ne sont PAS acceptées
Évitez de soumettre des demandes de tirage basées uniquement sur du refactoring. Corrigez plutôt un bug ou implémentez une fonctionnalité tout en améliorant le code.
Soumission de code sur GitHub
Flux de travail étape par étape
-
Cloner le dépôt Discourse :
git clone https://github.com/discourse/discourse.git -
Créer une nouvelle branche :
cd discourse git checkout -b new_discourse_branch -
Coder :
- Respectez les conventions de code existantes que vous trouvez dans le code.
- Incluez des tests et assurez-vous qu’ils passent.
- Référez-vous aux discussions pertinentes sur le forum meta de Discourse.
-
Respecter les conventions de codage :
- deux espaces, pas de tabulations
- pas d’espaces de fin, les lignes vides ne doivent pas contenir d’espaces
- utiliser des espaces autour des opérateurs, après les virgules, les deux-points, les points-virgules, autour de
{et avant} - pas d’espace après
(,[ou avant],) - utiliser la syntaxe des hachages Ruby 1.9 : privilégier
{ a: 1 }à{ :a => 1 } - privilégier
class << self; def method; endàdef self.methodpour les méthodes de classe - privilégier
{ ... }àdo ... endpour les blocs sur une seule ligne, éviter d’utiliser{ ... }pour les blocs sur plusieurs lignes - éviter
returnlorsqu’il n’est pas nécessaire
-
Valider (Commit) :
git commit -m "Un résumé court du changement" -m "Une description détaillée du changement"Ne laissez jamais un message de commit vide — ce guide est utile pour écrire des messages de commit. Le message doit commencer par un résumé court (max 72 caractères) sur la première ligne, suivi d’une ligne vide, puis d’une description plus détaillée du changement. Vous pouvez utiliser la syntaxe Markdown pour un style simple si nécessaire.
Assurez-vous de préfixer les titres des commits selon les conventions de Discourse.
5 (a). Linting :
Le code JavaScript est linté avec eslint et formaté avec prettier. Ruby est linté avec RuboCop et formaté avec Syntax Tree. SCSS/CSS est linté avec stylelint. Les templates Ember sont lintés avec ember-template-lint. Toutes ces vérifications sont exécutées automatiquement dans les actions GitHub chaque fois que vous créez une demande de tirage pour Discourse.- Il est fortement recommandé d’installer nos hooks git pre-commit en utilisant
lefthook. Cela s’exécutera automatiquement chaque fois que vous ferez un commit dans le noyau de Discourse, et signalera les problèmes liés aux différents langages et templates avant que vous ne les poussiez et n’ayez à attendre que le CI de GitHub s’exécute. Exécutez ceci à la racine de votre projet :pnpm lefthook install
- Il est fortement recommandé d’installer nos hooks git pre-commit en utilisant
-
Mettre à jour votre branche :
git fetch origin git rebase origin/main -
Forker :
git remote add mine git@github.com:<your-username>/discourse.git -
Pousser vers votre dépôt distant :
git push mine new_discourse_branch -
Émettre une demande de tirage (pull request) :
- Accédez à votre dépôt sur GitHub.
- Cliquez sur « Pull Request ».
- Écrivez le nom de votre branche dans le champ de la branche.
- Cliquez sur « Update Commit Range ».
- Vérifiez les changements dans les onglets « Commits » et « Files Changed ».
- Fournissez un titre et une description.
- Cliquez sur « Send pull request ».
Avant de soumettre une demande de tirage, nettoyez l’historique, passez en revue vos commits et regroupez (squash) les petits changements et corrections dans les commits correspondants. Vous pouvez regrouper des commits avec la commande de rebase interactive :
git fetch origin
git checkout new_discourse_branch
git rebase origin/main
git rebase -i
< l'éditeur s'ouvre et vous permet de modifier l'historique des commits >
< suivez les instructions en bas de l'éditeur >
git push -f mine new_discourse_branch
- Répondre aux commentaires :
- Soyez réceptif aux commentaires et prêt à mettre en œuvre les changements suggérés.
- Rappelez-vous que les commentaires signifient que votre travail est valorisé et destiné à être inclus.
Merci de contribuer au projet open-source Discourse !