このガイドは、Discourse オープンソースプロジェクトに貢献したい人を対象に、効果的なコラボレーションに必要なセットアップと規約を詳述しています。
必要なユーザーレベル: コードへの貢献は誰でも可能ですが、Ruby と JavaScript に精通している必要があります。
概要
このドキュメントでは、以下のトピックをカバーします:
- 開発環境のセットアップ
- 貢献を開始する場所の理解
- Discourse プラグインの作成と操作
- Discourse コアへの貢献
- 従うべきコーディング規約
- GitHub への貢献の提出
開発環境のセットアップ
貢献を始める前に、開発環境が適切に設定されていることを確認してください。お使いのプラットフォームに適したガイドに従ってください:
- 全プラットフォーム: Docker を使用して開発用に Discourse をインストールする
- Mac OS X: macOS での開発用 Discourse インストール初心者のためのガイド
- Linux (Ubuntu): Ubuntu での開発用 Discourse インストール初心者のためのガイド
- Windows: Windows 10 での開発用 Discourse インストール初心者のためのガイド
貢献の開始場所を知る
Discourse は大規模なプロジェクトであり、Ruby や JavaScript などの基盤技術を理解することが不可欠です。始め方に関するガイダンスについては、初心者向けガイドを参照してください。
プラグインの作成と操作
プラグインは、Discourse の内部構造を扱いやすい部分で理解し、コード貢献を容易に始める方法を提供します。以下から始めてください:
- Developing Discourse Plugins - Part 1 - Create a basic plugin
- (deprecated) Plugin outlet locations theme component
インスピレーションを得るために、Contribute > Feature および #plugin:extras で人気のアイデアを探ってみてください。
Discourse コアへの貢献
Discourse コアのコードは、GitHub 上のコアリポジトリ で管理されています。
CLA の署名
貢献する前に、電子 Discourse フォーラム 貢献利用許諾契約書 を読み、署名してください。CLA に署名していないユーザーからのプルリクエスト (PR) を、チームは法的に受け入れることができません。
入門タスクで慣れる
pr-welcome タグをチェックし、始めるのに適したタスクを探してください。
バグリストを処理する
お気に入り順に並べられたオープンなバグのリスト からバグを修正してください。バグの修正に取り掛かっている場合はメモを残してください。完了できない場合、他の人が作業を継続できるよう、関連するメモを残してください。
機能トピックの支援
機能リクエスト への詳細やモックアップの提供に貢献し、承認プロセスを支援してください。なお、すべての機能がコアに含まれるわけではない ことを覚えておいてください。
パフォーマンスの改善
クライアント側またはサーバー側のパフォーマンスを向上させるプルリクエストを歓迎します。特に、フロントページの初期読み込みやトピックビューなどの高インパクト領域に焦点を当ててください。
Discourse が管理するプロジェクトの改善
Discourse が管理する他のオープンソースプロジェクトに貢献してください。代表的なプロジェクトには以下が含まれます:
- Logster - ウェブ GUI ログビューア
- Message Bus - サイトのライブインタラクション用エンジン
- Rack Mini Profiler - 診断ツール
- Discourse API - API コンシューマー
- Discourse Docker - Discourse 配布エンジン
- WP Discourse - WordPress プラグイン
- Memory Profiler - Ruby 用プロファイラー
- Ember Performance - Ember パフォーマンステストスイート
コーディング規約
命名は重要
サイト上で使用される用語と、データベース内のクラス名および列名の間に 100% の整合性を持たせるようにしてください (例: “posts”)。
依存関係の最新バージョンとの互換性は重要
Rails、Ruby、Ember などのライブラリの最新安定版との互換性を確保してください。依存関係を更新する際には、リグレッションがないかテストしてください。
テストのみの貢献は歓迎
テストされていないプロセスやコントローラーアクションに対するテスト貢献は歓迎されます。やむを得ない場合を除き、モックの使用は避けてください。
リファクタリングのみの貢献は歓迎されません
リファクタリングのみのプルリクエストを送信しないでください。代わりに、バグを修正するか機能を実装しつつ、コードを改善してください。
GitHub へのコードの提出
ステップバイステップのワークフロー
-
Discourse リポジトリをクローンする:
git clone https://github.com/discourse/discourse.git -
新しいブランチを作成する:
cd discourse git checkout -b new_discourse_branch -
コーディング:
- コード内に見つかった既存のコーディング規約に従ってください。
- テストを含め、テストが成功することを確認してください。
- Discourse メタフォーラム 上の関連するディスカッションを参照してください。
-
コーディング規約に従う:
- 2スペースのインデント、タブは使用しない
- 末尾の空白なし、空行にはスペースを含めない
- 演算子の周り、カンマ、コロン、セミコロンの後、
{の周り、}の前にスペースを使用する (、[の後、]、)の前にスペースを入れない- Ruby 1.9 のハッシュ構文を使用する:
{ :a => 1 }より{ a: 1 }を優先する - クラスメソッドには
def self.methodよりclass << self; def method; endを優先する - 1行のブロックには
{ ... }を、複数行のブロックにはdo ... endを使用し、複数行ブロックに{ ... }を使用しない - 必要でない限り
returnを避ける
-
コミットする:
git commit -m "変更の短い要約" -m "変更の詳細な説明"コミットメッセージを空白のままにしないでください。コミットメッセージの書き方に関する有用なガイドがあります。メッセージは、1行目に短い要約 (最大 72 文字) で始まり、空行を挟んでから、変更の詳細な説明が続く形にしてください。必要に応じてマークダウン構文を使用して簡単な書式設定を行うことができます。
コミットタイトルには、Discourse の規約 に従ってプレフィックスを付けてください。
5 (a). リンティング:
JavaScript コードは eslint でリンティングされ、prettier でフォーマットされます。Ruby は RuboCop でリンティングされ、Syntax Tree でフォーマットされます。SCSS/CSS は stylelint でリンティングされます。Ember テンプレートは ember-template-lint でリンティングされます。これらのチェックはすべて、Discourse へのプルリクエストを作成する際に GitHub Actions で自動的に実行されます。lefthookを使用してプリコミット git フックをインストールすることを強く推奨します。これにより、Discourse コアでコミットするたびに自動的に実行され、GitHub CI の実行を待たずに、コードやテンプレートに関する問題を早期に検出できます。プロジェクトのルートで以下を実行してください:pnpm lefthook install
-
ブランチを更新する:
git fetch origin git rebase origin/main -
フォークする:
git remote add mine git@github.com:<your-username>/discourse.git -
リモートにプッシュする:
git push mine new_discourse_branch -
プルリクエスト を発行する:
- GitHub 上のリポジトリに移動します。
- 「Pull Request」をクリックします。
- ブランチフィールドにブランチ名を入力します。
- 「Update Commit Range」をクリックします。
- 「Commits」および「Files Changed」タブで変更内容を確認します。
- タイトルと説明を入力します。
- 「Send pull request」をクリックします。
プルリクエストを送信する前に、履歴を整理し、コミットを確認して、小さな変更や修正を対応するコミットに squash (統合) してください。インタラクティブリベースコマンドを使用してコミットを squash できます:
git fetch origin
git checkout new_discourse_branch
git rebase origin/main
git rebase -i
< エディターが開き、コミット履歴の変更が可能になります >
< エディターの下部にある指示に従ってください >
git push -f mine new_discourse_branch
- フィードバックに対応する:
- フィードバックに迅速に対応し、提案された変更を実装する準備をしてください。
- フィードバックは、あなたの仕事が評価され、統合される意図があることを意味します。
Discourse オープンソースプロジェクトへの貢献、ありがとうございます！