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 beisteuern, aber Sie sollten mit Ruby und JavaScript vertraut sein.

Zusammenfassung

Diese Dokumentation behandelt die folgenden Punkte:

  • 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 mit dem Beitrag beginnen kann

Discourse ist ein großes Projekt, und das Verständnis seiner zugrunde liegenden Technologien wie Ruby und JavaScript ist unerlässlich. Als Orientierungshilfe, wie Sie anfangen können, 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:

Suchen Sie nach Inspiration in beliebten Ideen unter Feature und Plugin > Extras.

Beitrag zum Discourse-Kern

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

Unterzeichnung der CLA

Bevor Sie einen Beitrag leisten, lesen und unterzeichnen Sie 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 für den Anfang an.

Durcharbeiten der Fehlerliste

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, um Ihre Arbeit fortzusetzen.

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 in den Kern aufgenommen.

Leistung verbessern

Wir freuen uns über 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

Test-Beiträ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 beinhalten. Beheben Sie stattdessen einen Fehler oder implementieren Sie eine Funktion und verbessern Sie dabei den Code.

Code auf GitHub einreichen

Schritt-für-Schritt-Workflow

  1. Das Discourse-Repository klonen:

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

  2. Einen neuen Branch erstellen:

    cd discourse
git checkout -b new_discourse_branch

  3. Codieren:

    • 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 durchlaufen.
    • Beziehen Sie sich auf relevante Diskussionen im Discourse Meta Forum.

  4. Codierungskonventionen befolgen:

    • zwei Leerzeichen, keine Tabs
    • keine nachgestellten 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: { a: 1 } gegenüber { :a => 1 } bevorzugen
    • class << self; def method; end gegenüber def self.method für Klassenmethoden bevorzugen
    • { ... } gegenüber do ... end für einzeilige Blöcke bevorzugen, { ... } für mehrzeilige Blöcke vermeiden
    • return vermeiden, wenn nicht erforderlich

  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 (maximal 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 Commit-Titel 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 bei jedem Commit im Discourse-Kern automatisch ausgeführt und melden Probleme mit den verschiedenen Sprachen und Vorlagen, bevor Sie sie pushen 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. Branch aktualisieren:

    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 „Update Commit Range“.
    • Überprüfen Sie die Änderungen in den Tabs „Commits“ und „Files Changed“.
    • Geben Sie einen Titel und eine Beschreibung ein.
    • Klicken Sie auf „Send pull request“.

    Bevor Sie einen Pull-Request einreichen, bereinigen Sie den Verlauf, 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, den Commit-Verlauf zu ändern >
< folgen Sie den Anweisungen am unteren Rand des Editors >

git push -f mine new_discourse_branch
  1. Auf Feedback reagieren:
    • 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 für Ihren Beitrag zum Open-Source-Projekt Discourse!

73 „Gefällt mir“
112

Wurde dies absichtlich entfernt?

Das funktioniert nicht mehr

2 „Gefällt mir“
114

Danke @Moin – ich habe dies im Thema behoben!

3 „Gefällt mir“
115

Hallo, gibt es eine Anleitung, wie man eine PR-Überprüfung anfordert?

Ich habe ein paar Pull-Anfragen eingereicht und es sieht so aus, als hätte das Discourse-Team sie leider übersehen. Das passiert, und das ist in Ordnung.
Aber es scheint keine Dokumentation darüber zu geben, wie man jemanden im Team respektvoll anpingt.

4 „Gefällt mir“
116

Ich verstehe. Als Richtlinie denke ich, dass ein erneuter Beitrag zum PR nach einem Monat in Ordnung ist. Außerdem können Sie ein Thema dazu eröffnen (oder auf ein bestehendes relevantes Thema auf Meta antworten).

3 „Gefällt mir“
117

Hallo Sam, ich habe tatsächlich versucht, einen PR zu pushen (hier), und es sieht so aus, als ob Pushes auf GitHub nicht auf die gleiche Weise funktionieren wie hier (er wird nicht an den Anfang der Liste verschoben).

Ich werde mich in Zukunft in die Dev-Kategorie begeben. Es wäre vielleicht gut, diese Kategorie im OP (entweder in oder vor Schritt Nr. 10) explizit zu erwähnen :slight_smile:

1 „Gefällt mir“
118

Wenn wir einen PR einreichen, der lokalisiert werden muss, fügen wir dann leere YAML-Strings in die config/locales-Dateien ein?