Contributing to Discourse development

Dokumentation Beitragen
1

:bookmark: Dieser Leitfaden richtet sich an alle, die zum Open-Source-Projekt Discourse beitragen möchten, und beschreibt die Einrichtung und Konventionen, die für eine effektive Zusammenarbeit erforderlich sind.

:person_raising_hand: Erforderliches Benutzerniveau: Jeder kann Code beitragen, aber Sie sollten mit Ruby und JavaScript vertraut sein.

Zusammenfassung

Diese Dokumentation behandelt Folgendes:

  • Einrichten Ihrer Entwicklungsumgebung
  • Verstehen, wo man mit dem Beitrag beginnen kann
  • Erstellen und Arbeiten mit Discourse-Plugins
  • Beitrag zum Discourse-Kern
  • Zu befolgende Codierungskonventionen
  • Einreichen Ihrer Beiträge auf GitHub

Einrichten der Entwicklungsumgebung

Bevor Sie mit dem Beitrag beginnen, stellen Sie sicher, dass Ihre Entwicklungsumgebung korrekt eingerichtet ist. Befolgen Sie die entsprechende Anleitung für Ihre Plattform:

Wo man anfangen soll

Discourse ist ein großes Projekt, und das Verständnis seiner zugrunde liegenden Technologien wie Ruby und JavaScript ist unerlässlich. Für eine Anleitung zum Einstieg lesen Sie bitte den Anfängerleitfaden.

Erstellen und Arbeiten mit Plugins

Plugins bieten eine Möglichkeit, die internen Abläufe von Discourse in überschaubaren Abschnitten zu verstehen und ermöglichen es Ihnen, einfach mit dem Beitragen von Code zu beginnen. Beginnen Sie mit:

Als Inspiration können Sie beliebte Ideen in Feature und Plugin > Extras erkunden.

Beitrag zum Discourse-Kern

Der Kerncode von Discourse wird im Core-Repository auf GitHub verwaltet.

Unterzeichnung der CLA

Lesen und unterzeichnen Sie vor dem Beitrag die Electronic Discourse Forums Contribution License Agreement. Das Team kann keine Pull Requests (PRs) von Benutzern rechtlich akzeptieren, die die CLA nicht unterzeichnet haben.

Aufwärmen mit Starter-Aufgaben

Sehen Sie sich das Tag pr-welcome für gute Aufgaben zum Einstieg an.

Bearbeiten der Bug-Liste

Beheben Sie Fehler aus der Liste der offenen Fehler, sortiert nach Likes. Hinterlassen Sie eine Notiz, wenn Sie an einem Fehler arbeiten – wenn Sie ihn nicht abschließen, hinterlassen Sie alle relevanten Notizen für jemand anderen, der Ihre Arbeit fortsetzen kann.

Hilfe bei Feature-Themen

Tragen Sie Details und Mockups zu Feature-Anfragen bei, um deren Genehmigungsprozess zu unterstützen. Denken Sie daran, nicht jedes Feature wird im Kern enthalten sein.

Leistung verbessern

Wir begrüßen Pull Requests, die die Client- oder Server-seitige Leistung verbessern, wobei der Schwerpunkt auf Bereichen mit hoher Auswirkung liegt, wie dem anfänglichen Laden der Startseite oder der Themenansicht.

Von Discourse gewartete Projekte verbessern

Tragen Sie zu anderen Open-Source-Projekten bei, die von Discourse gewartet werden. Einige bemerkenswerte Projekte sind:

Codierungskonventionen

Benennung ist ENTSCHEIDEND

Streben Sie 100%ige Übereinstimmung zwischen den auf der Website verwendeten Begriffen und den Namen von Klassen und Spalten in der Datenbank an (z. B. „posts“).

Kompatibilität mit den neuesten Versionen von Abhängigkeiten ist ENTSCHEIDEND

Stellen Sie die Kompatibilität mit den neuesten stabilen Versionen von Bibliotheken wie Rails, Ruby und Ember sicher. Testen Sie auf Regressionen, wenn Sie Abhängigkeiten aktualisieren.

Nur-Test-Beiträge sind willkommen

Testbeiträge sind willkommen, insbesondere für nicht getestete Prozesse und Controller-Aktionen. Vermeiden Sie Mocking, es sei denn, es ist absolut notwendig.

Nur-Refactoring-Beiträge sind NICHT willkommen

Vermeiden Sie das Einreichen von Pull Requests, die nur Refactoring enthalten. Beheben Sie stattdessen einen Fehler oder implementieren Sie eine Funktion, während Sie den Code verbessern.

Einreichen von Code auf GitHub

Schritt-für-Schritt-Workflow

  1. Klonen Sie das Discourse-Repository:

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

  2. Erstellen Sie einen neuen Branch:

    cd discourse
git checkout -b new_discourse_branch

  3. Code:

    • Halten Sie sich an die bestehenden Code-Konventionen, die Sie im Code finden.
    • Fügen Sie Tests hinzu und stellen Sie sicher, dass sie erfolgreich sind.
    • Verweisen Sie auf relevante Diskussionen im Discourse-Meta-Forum.

  4. Befolgen Sie die Codierungskonventionen:

    • zwei Leerzeichen, keine Tabs
    • keine abschließenden Leerzeichen, leere Zeilen sollten keine Leerzeichen enthalten
    • Leerzeichen um Operatoren, nach Kommas, Doppelpunkten, Semikolons, um { und vor }
    • kein Leerzeichen nach (, [ oder vor ], )
    • Ruby 1.9 Hash-Syntax verwenden: bevorzugen Sie { a: 1 } gegenüber { :a => 1 }
    • bevorzugen Sie class << self; def method; end gegenüber def self.method für Klassenmethoden
    • bevorzugen Sie { ... } gegenüber do ... end für einzeilige Blöcke, vermeiden Sie die Verwendung von { ... } für mehrzeilige Blöcke
    • vermeiden Sie return, wenn es nicht erforderlich ist

  5. Commit:

    git commit -m "Eine kurze Zusammenfassung der Änderung" -m "Eine detaillierte Beschreibung der Änderung"

    Lassen Sie eine Commit-Nachricht niemals leer – dies ist ein hilfreicher Leitfaden zum Schreiben von Commit-Nachrichten. Die Nachricht sollte mit einer kurzen (max. 72 Zeichen) Zusammenfassung in der ersten Zeile beginnen, gefolgt von einer Leerzeile und dann einer detaillierteren Beschreibung der Änderung. Sie können bei Bedarf Markdown-Syntax für einfache Formatierungen verwenden.

    Stellen Sie sicher, dass Sie die Titel der Commits gemäß den Discourse-Konventionen präfixen.

    5 (a). Linting:
    JavaScript-Code wird mit eslint und Formatierungsbedingungen von prettier gelintet. Ruby wird mit RuboCop gelintet. Alle diese Prüfungen werden automatisch in GitHub Actions ausgeführt, wann immer Sie einen Pull Request für Discourse erstellen.

    • Es wird dringend empfohlen, unsere Pre-Commit-Git-Hooks mit lefthook zu installieren. Diese werden automatisch jedes Mal ausgeführt, wenn Sie einen Commit im Discourse-Kern erstellen, und melden Probleme mit den verschiedenen Sprachen und Vorlagen, bevor Sie sie hochladen und warten müssen, bis GitHub CI ausgeführt wird. Führen Sie dies in Ihrem Projektstammverzeichnis aus:
      mkdir .git/hooks
npx lefthook install

  6. Aktualisieren Sie Ihren Branch:

    git fetch origin
git rebase origin/main

  7. Forken:

    git remote add mine git@github.com:<your-username>/discourse.git

  8. Auf Ihr Remote pushen:

    git push mine new_discourse_branch

  9. Einen Pull Request erstellen:

    • Navigieren Sie zu Ihrem Repository auf GitHub.
    • Klicken Sie auf „Pull Request“.
    • Geben Sie Ihren Branch-Namen im Feld „branch“ ein.
    • Klicken Sie auf „Commit-Bereich aktualisieren“.
    • Überprüfen Sie die Änderungen in den Registerkarten „Commits“ und „Geänderte Dateien“.
    • Geben Sie einen Titel und eine Beschreibung ein.
    • Klicken Sie auf „Pull Request senden“.

    Bereinigen Sie vor dem Einreichen eines Pull-Requests die Historie, gehen Sie Ihre Commits durch und führen Sie kleinere Änderungen und Korrekturen in den entsprechenden Commits zusammen. Sie können Commits mit dem interaktiven Rebase-Befehl zusammenführen:

git fetch origin
git checkout new_discourse_branch
git rebase origin/main
git rebase -i

< der Editor öffnet sich und ermöglicht Ihnen, die Commit-Historie zu ändern >
< folgen Sie den Anweisungen am unteren Rand des Editors >

git push -f mine new_discourse_branch
  1. Auf Feedback antworten:
    • Reagieren Sie auf Feedback und seien Sie bereit, vorgeschlagene Änderungen umzusetzen.
    • Denken Sie daran, Feedback bedeutet, dass Ihre Arbeit geschätzt wird und zur Aufnahme vorgesehen ist.

Vielen Dank, dass Sie zum Open-Source-Projekt Discourse beitragen!

73 „Gefällt mir“