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 n’importe qui puisse contribuer du code, vous devrez être familiarisé avec Ruby et JavaScript.
Résumé
Cette documentation couvrira les points suivants :
- Configuration de votre environnement de développement
- Comprendre par où commencer à contribuer
- Création et utilisation des plugins Discourse
- Contribution au cœur de Discourse
- Conventions de codage à suivre
- 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 grand projet, et comprendre ses technologies sous-jacentes telles que Ruby et JavaScript est essentiel. Pour obtenir des conseils sur la façon de commencer, consultez le guide du débutant.
Création et utilisation des plugins
Les plugins offrent un moyen de comprendre les internes de Discourse en portions gérables 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 l’inspiration, explorez les idées populaires dans #feature et #plugin:extras.
Contribution au cœur de Discourse
Le code principal de Discourse est géré dans le dépôt principal sur GitHub.
Signature du CLA
Avant de contribuer, lisez et signez l’Accord de Licence de Contribution des Forums Électroniques Discourse. L’équipe ne peut légalement accepter les demandes de tirage (PRs) des utilisateurs qui n’ont pas signé le CLA.
Échauffement avec des tâches de départ
Explorez le tag pr-welcome pour trouver de bonnes tâches pour commencer.
Parcourir la liste des bugs
Corrigez les bugs de la liste des bugs ouverts classés par ‘likes’. Laissez une note si vous travaillez sur un bug - si vous ne le terminez pas, laissez toutes les notes pertinentes pour que quelqu’un d’autre puisse continuer votre travail.
Aide avec 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, toutes les fonctionnalités ne seront pas incluses dans le cœur.
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 de la vue de sujet.
Améliorer les projets maintenus par Discourse
Contribuez à d’autres projets open source maintenus par Discourse. Certains projets notables incluent :
- Logster - visualiseur de logs GUI web
- Message Bus - moteur pour les interactions de site en direct
- 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 Ember
Conventions de codage
La dénomination est CRUCIALE
Visez une parité à 100 % entre les termes utilisés sur le site et les noms des classes et des colonnes dans la base de données (par exemple, « posts »).
La compatibilité avec les dernières versions des dépendances est CRUCIALE
Assurez la compatibilité avec les dernières versions stables des bibliothèques comme Rails, Ruby et Ember. Testez les régressions lors de la mise à jour des dépendances.
Les contributions de test uniquement sont les bienvenues
Les contributions de tests sont bienvenues, en particulier pour les processus non testés et les actions de contrôleur. Évitez le mocking sauf si absolument nécessaire.
Les contributions de refactorisation uniquement NE SONT PAS les bienvenues
Évitez de soumettre des demandes de tirage de refactorisation uniquement. Au lieu de cela, corrigez 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 :
- Adhérez aux conventions de codage existantes que vous trouvez dans le code.
- Incluez des tests et assurez-vous qu’ils passent.
- Référencez les discussions pertinentes sur le forum méta de Discourse.
-
Suivre les conventions de codage :
- deux espaces, pas de tabulations
- pas d’espaces de fin, les lignes vides ne doivent pas contenir d’espaces
- utilisez 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],) - syntaxe de hachage Ruby 1.9 : préférez
{ a: 1 }à{ :a => 1 } - préférez
class << self; def method; endàdef self.methodpour les méthodes de classe - préférez
{ ... }àdo ... endpour les blocs sur une seule ligne, évitez d’utiliser{ ... }pour les blocs sur plusieurs lignes - évitez
returnlorsque ce n’est pas nécessaire
-
Commit :
git commit -m "Un bref résumé du changement" -m "Une description détaillée du changement"Ne laissez jamais un message de commit vide - ce guide est utile pour rédiger 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 de commit conformément aux conventions de Discourse.
5 (a). Linting (Vérification du style) :
Le code JavaScript est vérifié avec eslint et formaté avec prettier. Ruby est vérifié avec RuboCop et formaté avec Syntax Tree. SCSS/CSS est vérifié avec stylelint. Les modèles Ember sont vérifié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 pré-commit en utilisant
lefthook. Cela s’exécutera automatiquement chaque fois que vous ferez un commit dans le cœur de Discourse, et signalera les problèmes avec les différents langages et modèles avant que vous ne les envoyiez et ayez à attendre l’exécution de CI sur GitHub. Exécutez ceci dans la racine de votre projet :pnpm lefthook install
- Il est fortement recommandé d’installer nos hooks git pré-commit en utilisant
-
Mettre à jour votre branche :
git fetch origin git rebase origin/main -
Forker :
git remote add mine git@github.com:<votre-nom-utilisateur>/discourse.git -
Pousser vers votre distant :
git push mine new_discourse_branch -
Émettre une demande de tirage :
- Naviguez vers votre dépôt sur GitHub.
- Cliquez sur « Pull Request ».
- Entrez le nom de votre branche dans le champ de 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, parcourez vos commits et fusionnez les changements mineurs et les correctifs dans les commits correspondants. Vous pouvez fusionner des commits avec la commande 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éactif aux commentaires et prêt à mettre en œuvre les changements suggérés.
- N’oubliez pas, les commentaires signifient que votre travail est apprécié et destiné à être inclus.
Merci de contribuer au projet open source Discourse !