Contributing to Discourse development

Documentation Contribuer
1

:bookmark: Ce guide est conçu pour ceux qui souhaitent contribuer au projet open-source Discourse, détaillant la configuration et les conventions nécessaires à une collaboration efficace.

:person_raising_hand: Niveau d’utilisateur requis : Bien que tout le monde puisse contribuer au code, vous devrez être familier avec Ruby et JavaScript.

Sommaire

Cette documentation couvrira les points suivants :

  • Configuration de votre environnement de développement
  • Comprendre par où commencer à contribuer
  • Création et travail avec les 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 :

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 des débutants.

Création et travail avec les plugins

Les plugins offrent un moyen de comprendre les internes de Discourse par portions gérables et vous permettent de commencer à contribuer du code facilement. Commencez par :

Pour l’inspiration, explorez les idées populaires dans Feature et Plugin > Extras.

Contribution au cœur de Discourse

Le code source 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 d’Electronic Discourse Forums. L’équipe ne peut légalement pas accepter les demandes de tirage (PR) des utilisateurs qui n’ont pas signé le CLA.

Échauffement avec des tâches de démarrage

Explorez le tag pr-welcome pour de bonnes tâches pour commencer.

Parcourir la liste des bogues

Corrigez les bogues de la liste des bogues ouverts classés par nombre de “j’aime”. Laissez une note si vous travaillez sur un bogue - si vous ne le terminez pas, laissez toutes les notes pertinentes pour que quelqu’un d’autre puisse continuer votre travail.

Aider 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. N’oubliez pas que 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 la vue de sujet.

Améliorer les projets maintenus par Discourse

Contribuez à d’autres projets open-source maintenus par Discourse. Certains projets notables incluent :

Conventions de codage

La nomination est CRUCIALE

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 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 test sont bienvenues, en particulier pour les processus et les actions de contrôleur non testés. Évitez de “moquer” (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 bogue ou implémentez une fonctionnalité tout en améliorant le code.

Soumission de code sur GitHub

Flux de travail étape par étape

  1. Cloner le dépôt Discourse :

    git clone git@github.com:discourse/discourse.git

  2. Créer une nouvelle branche :

    cd discourse
git checkout -b new_discourse_branch

  3. Coder :

    • Respectez les 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.

  4. 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 ], )
    • utilisez la syntaxe de hachage Ruby 1.9 : préférez { a: 1 } à { :a => 1 }
    • préférez class << self; def method; end à def self.method pour les méthodes de classe
    • préférez { ... } à do ... end pour les blocs sur une seule ligne, évitez d’utiliser { ... } pour les blocs sur plusieurs lignes
    • évitez return lorsque ce n’est pas nécessaire

  5. Commiter :

    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 selon les conventions de Discourse.

    5 (a). Linter :
    Le code JavaScript est analysé avec eslint et les conditions de formatage de prettier. Ruby est analysé avec RuboCop. 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 effectuerez 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 que vous deviez attendre l’exécution du CI GitHub. Exécutez ceci dans la racine de votre projet :
      mkdir .git/hooks
npx lefthook install

  6. Mettre à jour votre branche :

    git fetch origin
git rebase origin/main

  7. Forker :

    git remote add mine git@github.com:<votre-nom-utilisateur>/discourse.git

  8. Pousser vers votre distant :

    git push mine new_discourse_branch

  9. É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, parcourez vos commits et fusionnez les changements mineurs et les corrections 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
  1. Répondre aux commentaires :
    • Soyez réactif aux commentaires et prêt à mettre en œuvre les changements suggérés.
    • Rappelez-vous, les commentaires signifient que votre travail est apprécié et destiné à être inclus.

Merci de contribuer au projet open-source Discourse !

73 « J'aime »