コントリビューションガイド

Fess プロジェクトへの貢献を歓迎します！ このページでは、Fess への貢献方法、コミュニティガイドライン、 プルリクエストの作成手順などを説明します。

はじめに

Fess はオープンソースプロジェクトであり、 コミュニティの貢献によって成長しています。 プログラミングの経験レベルに関係なく、誰でも貢献できます。

貢献の方法

Fess へは、さまざまな方法で貢献できます。

コードの貢献

  • 新機能の追加

  • バグ修正

  • パフォーマンスの改善

  • リファクタリング

  • テストの追加

ドキュメントの貢献

  • ユーザーマニュアルの改善

  • API ドキュメントの追加・更新

  • チュートリアルの作成

  • 翻訳

Issue の報告

  • バグレポート

  • 機能リクエスト

  • 質問や提案

コミュニティ活動

  • GitHub Discussions での議論

  • フォーラムでの質問への回答

  • ブログ記事やチュートリアルの執筆

  • イベントでの発表

初めての貢献

初めて Fess に貢献する場合は、以下のステップをお勧めします。

Step 1: プロジェクトを理解する

  1. Fess 公式サイト で基本情報を確認

  2. オープンソース全文検索サーバー - Fess 開発概要 で開発の概要を理解

  3. アーキテクチャとコード構造 でコード構造を学習

Step 2: Issue を探す

GitHub の Issue ページ で good first issue ラベルが付いた Issue を探します。

これらの Issue は、初めての貢献者に適した比較的簡単なタスクです。

Step 3: 開発環境をセットアップ

開発環境のセットアップ に従って、開発環境を構築します。

Step 4: ブランチを作成して作業

開発ワークフロー に従って、ブランチを作成し、コーディングを開始します。

Step 5: プルリクエストを作成

変更をコミットし、プルリクエストを作成します。

コーディング規約

Fess では、一貫性のあるコードを維持するため、 以下のコーディング規約に従っています。

Javaコーディングスタイル

基本スタイル

  • インデント: スペース 4 つ

  • 改行コード: LF（Unix スタイル）

  • エンコーディング: UTF-8

  • 行の長さ: 140 文字以内を推奨

命名規則

  • パッケージ: 小文字、ドット区切り（例: org.codelibs.fess）

  • クラス: PascalCase（例: SearchService）

  • インターフェース: PascalCase（例: Crawler）

  • メソッド: camelCase（例: executeSearch）

  • 変数: camelCase（例: searchResult）

  • 定数: UPPER_SNAKE_CASE（例: MAX_SEARCH_SIZE）

コメント

Javadoc:

public なクラス、メソッド、フィールドには Javadoc を記述します。

/**
 * 検索を実行します。
 *
 * @param query 検索クエリ
 * @return 検索結果
 * @throws SearchException 検索に失敗した場合
 */
public SearchResponse executeSearch(String query) throws SearchException {
    // 実装
}

実装コメント:

複雑なロジックには、日本語または英語でコメントを追加します。

// クエリの正規化（全角を半角に変換）
String normalizedQuery = QueryNormalizer.normalize(query);

クラスとメソッドの設計

  • 単一責任の原則: 1 つのクラスは 1 つの責任のみを持つ

  • 小さなメソッド: 1 つのメソッドは 1 つのことだけを行う

  • 意味のある名前: クラス名、メソッド名は意図が明確になるように

例外処理

// 良い例: 適切な例外処理
try {
    executeSearch(query);
} catch (IOException e) {
    logger.error("検索中にエラーが発生しました", e);
    throw new SearchException("検索の実行に失敗しました", e);
}

// 避けるべき例: 空のcatchブロック
try {
    executeSearch(query);
} catch (IOException e) {
    // 何もしない
}

null の扱い

  • 可能な限り null を返さない

  • Optional の使用を推奨

  • @Nullable アノテーションで null 可能性を明示

// 良い例
public Optional<User> findUser(String id) {
    return Optional.ofNullable(userMap.get(id));
}

// 使用例
findUser("123").ifPresent(user -> {
    // ユーザーが存在する場合の処理
});

テストの記述

  • すべての public メソッドにテストを書く

  • テストメソッド名は test で始める

  • Given-When-Then パターンを使用

@Test
public void testSearch() {
    // Given: テストの前提条件
    SearchService service = new SearchService();
    String query = "test";

    // When: テスト対象の実行
    SearchResponse response = service.search(query);

    // Then: 結果の検証
    assertNotNull(response);
    assertEquals(10, response.getDocuments().size());
}

コードレビューのガイドライン

プルリクエストのレビュープロセス

  1. 自動チェック: CI が自動的にビルドとテストを実行

  2. コードレビュー: メンテナーがコードをレビュー

  3. フィードバック: 必要に応じて修正依頼

  4. 承認: レビューが承認される

  5. マージ: メンテナーが main ブランチにマージ

レビュー観点

レビューでは、以下の点を確認します：

機能性

  • 要件を満たしているか

  • 意図した通りに動作するか

  • エッジケースが考慮されているか

コード品質

  • コーディング規約に従っているか

  • 読みやすく保守しやすいコードか

  • 適切な抽象化がされているか

テスト

  • 十分なテストが書かれているか

  • テストがパスするか

  • テストが意味のある検証をしているか

パフォーマンス

  • パフォーマンスへの影響はないか

  • リソースの使用は適切か

セキュリティ

  • セキュリティ上の問題はないか

  • 入力検証は適切か

ドキュメント

  • 必要なドキュメントが更新されているか

  • Javadoc が適切に書かれているか

レビューコメントへの対応

レビューコメントには、迅速かつ丁寧に対応します。

修正が必要な場合:

ご指摘ありがとうございます。修正しました。
[修正内容の簡単な説明]

議論が必要な場合:

ご意見ありがとうございます。
○○の理由で現在の実装としていますが、
△△という実装の方が良いでしょうか？

プルリクエストのベストプラクティス

PR の大きさ

  • 小さく、レビューしやすい PR を心がける

  • 1 つの PR には 1 つの論理的な変更を含める

  • 大きな変更は複数の PR に分割

PR のタイトル

明確で説明的なタイトルを付けます：

feat: 検索結果のフィルタリング機能を追加
fix: クローラーのタイムアウト問題を修正
docs: API ドキュメントを更新

PR の説明

以下の情報を含めます：

  • 変更内容: 何を変更したか

  • 理由: なぜこの変更が必要か

  • テスト方法: どのようにテストしたか

  • スクリーンショット: UI 変更の場合

  • 関連 Issue: Issue 番号（例: Closes #123）

## 変更内容
検索結果をファイルタイプでフィルタリングできる機能を追加しました。

## 理由
ユーザーから「特定のファイルタイプのみを検索したい」という
要望が多数寄せられていたため。

## テスト方法
1. 検索画面でファイルタイプフィルターを選択
2. 検索を実行
3. 選択したファイルタイプの結果のみが表示されることを確認

## 関連 Issue
Closes #123

コミットメッセージ

明確で説明的なコミットメッセージを書きます：

<type>: <subject>

<body>

<footer>

例:

feat: 検索フィルター機能を追加

ユーザーが検索結果をファイルタイプでフィルタリングできるようにしました。

- フィルターUI の追加
- バックエンドのフィルター処理を実装
- テストを追加

Closes #123

Draft PR の活用

作業中の PR は Draft PR として作成し、 完成したら Ready for review に変更します。

1. PR 作成時に「Create draft pull request」を選択
2. 作業が完了したら「Ready for review」をクリック

コミュニティガイドライン

行動規範

Fess コミュニティでは、以下の行動規範を遵守します：

  • 敬意を持つ: すべての人を尊重する

  • 協力的である: 建設的なフィードバックを提供する

  • オープンである: 異なる視点や経験を歓迎する

  • 礼儀正しい: 丁寧な言葉遣いを心がける

コミュニケーション

質問する場所:

質問の仕方:

  • 具体的に質問する

  • 試したことを説明する

  • エラーメッセージやログを含める

  • 環境情報（OS、Java バージョンなど）を記載

回答の仕方:

  • 丁寧に、親切に

  • 具体的な解決策を提示

  • 参考資料へのリンクを提供

感謝の表明

貢献に対しては、感謝の気持ちを表明します。 小さな貢献でも、プロジェクトにとって価値があります。

よくある質問

Q: 初心者でも貢献できますか？

A: はい、歓迎します！good first issue ラベルの Issue から始めることをお勧めします。 ドキュメントの改善も初心者に適した貢献です。

Q: プルリクエストはどのくらいで レビューされますか？

A: 通常、数日以内にレビューします。 ただし、メンテナーのスケジュールによって前後する場合があります。

Q: プルリクエストが却下された場合は？

A: 却下の理由を確認し、必要に応じて修正して再提出できます。 分からない点があれば、気軽に質問してください。

Q: コーディング規約に違反している場合は？

A: レビューで指摘されるので、修正すれば問題ありません。 mvn formatter:format を実行することで、事前にコードフォーマットをチェック・修正できます。また、 mvn license:format でライセンスヘッダーも自動整形できます。

Q: 大きな機能を追加したい場合は？

A: まず Issue を作成し、提案内容を議論することをお勧めします。 事前に合意を得ることで、作業の無駄を避けられます。

Q: 日本語で質問しても良いですか？

A: はい、日本語でも英語でも構いません。 Fess は日本発のプロジェクトなので、日本語のサポートも充実しています。

貢献の種類別ガイド

ドキュメントの改善

  1. ドキュメントのリポジトリをフォーク：

    git clone https://github.com/codelibs/fess-docs.git

  2. 変更を加える

  3. プルリクエストを作成

バグ報告

  1. 既存の Issue を検索して重複を確認

  2. 新しい Issue を作成

  3. 以下の情報を含める：

    • バグの説明

    • 再現手順

    • 期待される動作

    • 実際の動作

    • 環境情報

機能リクエスト

  1. Issue を作成

  2. 以下を説明：

    • 機能の説明

    • 背景と動機

    • 提案する実装方法（任意）

コードレビュー

他の人のプルリクエストをレビューすることも貢献になります：

  1. 興味のある PR を見つける

  2. コードを確認

  3. 建設的なフィードバックを提供

ライセンス

Fess は Apache License 2.0 のもとで公開されています。 貢献されたコードも同じライセンスが適用されます。

プルリクエストを作成することで、 あなたの貢献がこのライセンスのもとで公開されることに同意したものとみなされます。

謝辞

Fess プロジェクトへの貢献に感謝します！ あなたの貢献が、Fess をより良いソフトウェアにします。

次のステップ

貢献の準備ができたら：

  1. 開発環境のセットアップ で開発環境をセットアップ

  2. 開発ワークフロー で開発フローを確認

  3. GitHub で Issue を探す

参考資料

コミュニティリソース