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 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 :
- Mise en place de votre environnement de développement
- Compréhension de là où commencer à contribuer
- Création et utilisation des plugins Discourse
- Contribution au noyau de Discourse
- Conventions de codage à respecter
- Soumission de vos contributions sur GitHub
Mise en place 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 en utilisant 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 volumineux, 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, référez-vous au guide pour les débutants.
Création et utilisation des plugins
Les plugins offrent un moyen de comprendre les internes de Discourse par parties gérables et vous permettent de commencer à contribuer au 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 Contribute > Feature et #plugin:extras.
Contribution au noyau 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 Discourse électroniques. L’équipe ne peut pas accepter légalement les demandes de tirage (PR) des utilisateurs qui n’ont pas signé la CLA.
S’échauffer 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 de la liste des bugs ouverts triés par nombre de « j’aime ». Laissez une note 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 avec les sujets de fonctionnalités
Contribuez aux détails et aux maquettes des 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 journaux 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 Discourse
- WP Discourse - plugin WordPress
- Memory Profiler - profileur pour Ruby
- Ember Performance - suite de tests de performance 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 exemple, « 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 comme Rails, Ruby et Ember. Testez les régressions lors de la mise à jour des dépendances.
Les contributions uniquement de test sont les bienvenues
Les contributions de test sont les bienvenues, en particulier pour les processus et les actions de contrôleur non testés. Évitez le mocking sauf si absolument nécessaire.
Les contributions uniquement de refactorisation ne sont PAS les bienvenues
Évitez de soumettre des demandes de tirage uniquement pour la refactorisation. 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 :
- 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 méta Discourse.
-
Suivre les conventions de codage :
- deux espaces, pas de tabulations
- pas d’espaces blancs en fin de ligne, 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 de hachage Ruby 1.9 : préférer
{ a: 1 }à{ :a => 1 } - préférer
class << self; def method; endàdef self.methodpour les méthodes de classe - préférer
{ ... }à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 - ceci est un guide 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 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 modèles 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 faites un commit dans le noyau Discourse, et signalera les problèmes avec les différents langages et modèles avant que vous ne les poussiez et n’ayez à attendre que le CI de GitHub s’exécute. Exécutez ceci dans 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 :
- Naviguez vers votre dépôt sur GitHub.
- Cliquez sur « Pull Request ».
- Écrivez 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, passez en revue vos commits et regroupez les petits changements et corrections dans les commits correspondants. Vous pouvez regrouper les 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, les commentaires signifient que votre travail est valorisé et destiné à être inclus.
Merci de contribuer au projet open-source Discourse !