# 貢献ガイド

`haniwers` プロジェクトへの貢献に興味を持っていただきありがとうございます。このドキュメントでは、プロジェクトへの貢献方法を説明します。

## プロジェクトに連絡する

バグ報告、機能要望、質問などがある場合は以下の方法で連絡できます：

- **GitLab Issues**: [https://gitlab.com/qumasan/haniwers/-/issues](https://gitlab.com/qumasan/haniwers/-/issues)

## Issue を作成する

バグ報告や機能要望は、GitLab Issues で管理しています。

### Issue 作成手順

#### CLI から作成（推奨）

```bash
# glab CLI を使用
glab issue create --template issue
```

#### Web UI から作成

1. [GitLab Issues ページ](https://gitlab.com/qumasan/haniwers/-/issues)にアクセス
2. 「New issue」をクリック
3. テンプレートから「issue」を選択
4. 必要な情報を記入して作成

### Issue テンプレート

プロジェクトでは `.gitlab/issue_templates/issue.md` のテンプレートを用意しています。以下のセクションを含めてください：

- **概要**: 何が問題か、何を実現したいか
- **期待される動作**: あるべき動作
- **現在の動作**: 実際の動作（バグの場合）
- **再現手順**: 問題を再現する手順
- **環境情報**: OS、Pythonバージョンなど

## 開発ワークフロー

### 1. リポジトリをクローンする

#### 基本的なクローン方法

デフォルトの `main` ブランチをクローンします：

```bash
git clone https://gitlab.com/qumasan/haniwers.git
cd haniwers
```

#### SSHでクローン（推奨）

SSHキーが設定されている場合は以下を使用します：

```bash
git clone git@gitlab.com:qumasan/haniwers.git
cd haniwers
```

#### 特定のタグを使用する

リリースバージョンを指定してクローンする場合：

```bash
# 1.7.0 などの特定のタグをクローン
git clone --branch 1.7.0 https://gitlab.com/qumasan/haniwers.git
cd haniwers
```

#### 浅いクローン（git history を短縮）

大きなリポジトリの場合、ダウンロード時間を短縮できます：

```bash
# 最新 1 コミットのみを取得
git clone --depth 1 https://gitlab.com/qumasan/haniwers.git
cd haniwers

# 特定のタグで浅いクローン
git clone --branch 1.7.0 --depth 1 https://gitlab.com/qumasan/haniwers.git
cd haniwers
```

#### 既存のクローンから特定のタグに切り替える

すでにクローンしている場合、タグを切り替えられます：

```bash
# 利用可能なタグを確認
git tag -l

# 特定のタグに切り替え
git switch 1.7.0 --detached

# タグの詳細を確認
git show 1.7.0
```

**注意**: タグに切り替えるとデタッチドヘッド状態になります。本格的な開発にはブランチの使用をオススメします：

```bash
# タグからブランチを作成して開発
git switch -c feature-from-1.7.0 1.7.0
```

### 2. 依存関係をインストールする

```bash
poetry install --with docs,dev
```

詳細は[開発環境セットアップ](./index.md#開発環境の構築手順)を参照してください。

### 3. 開発ブランチを作成する

#### ブランチ命名規則

ブランチ名は以下のルールにしたがってください：

- **シンプルで内容がわかる名前**
- **アルファベットを使用**（日本語不可）
- **プリフィックス形式**: `prefix-branch-name`
  - ✅ 良い例: `feat-awesome`, `fix-threshold-bug`, `docs-update-readme`
  - ❌ 悪い例: `feat/awesome`, `fix/xxx`

#### ブランチの作成

```bash
# ブランチを作成
git branch feat-new-feature

# ブランチを確認
git branch
```

### 4. Git Worktree で作業スペースを作成する（推奨）

`git worktree` を使うと、ブランチごとに隔離された作業環境を作成できます。

```bash
# 作業スペースを作成
git worktree add ../worktrees/feat-new-feature feat-new-feature

# 作業スペースに移動
cd ../worktrees/feat-new-feature

# 依存関係をインストール
poetry install
```

#### なぜ git worktree を使うのか？

- ブランチごとの作業内容が隔離される
- 複数のブランチを同時に開発できる
- `git stash` や `git pop` が不要
- ディレクトリを変更するだけでブランチを切り替えられる

### 5. 開発する

```bash
# テストを実行
poetry run pytest

# コードフォーマット
poetry run ruff format .

# 静的解析
poetry run ruff check .

# pre-commit フックを実行
poetry run pre-commit run --all-files
```

詳細は[テストガイドライン](./testing.md)を参照してください。

### 6. コミットを作成する

このプロジェクトでは **Conventional Commits** 形式を採用しています。

#### Commitizen を使用（推奨）

```bash
# ファイルをステージング
git add 変更したファイル

# Commitizen で対話的にコミット
cz c
```

#### 手動でコミット

```bash
git commit -m "feat(module): add new feature description"
```

#### コミットタイプ

- `feat`: 新機能
- `fix`: バグ修正
- `docs`: ドキュメントのみの変更
- `style`: コードの意味に影響しない変更（スペース、フォーマットなど）
- `refactor`: リファクタリング
- `perf`: パフォーマンス改善
- `test`: テストの追加・修正
- `build`: ビルドシステムや依存関係の変更
- `ci`: CI設定ファイルの変更
- `chore`: その他の変更

#### 破壊的変更

破壊的変更がある場合は、タイプの後に `!` を追加します：

```bash
git commit -m "feat(api)!: remove deprecated endpoint"
```

### 7. Pre-commit フックで事前チェック

```bash
# pre-commit をインストール（初回のみ）
pre-commit install

# すべてのファイルをチェック
pre-commit run --all-files
```

pre-commit の設定は `.pre-commit-config.yaml` で確認できます。

### 8. マージリクエスト（MR）を作成する

#### リモートにプッシュ

```bash
# メインブランチの変更を取り込む
git fetch origin
git rebase origin/main  # または git merge origin/main

# リモートにプッシュ
git push --set-upstream origin feat-new-feature
```

#### MRを作成

##### CLIから作成（推奨）

```bash
glab mr create --target-branch main --template draft
```

##### WebUIから作成

プッシュ後、ターミナルに表示されるGitLabのMR作成リンクをクリックします。

#### MRテンプレート

プロジェクトでは `.gitlab/merge_request_templates/draft.md` のテンプレートを用意しています。以下のセクションを含めてください：

- **Summary**: 変更の概要（1-3 bullet points）
- **Test plan**: テスト計画のチェックリスト
- **Related Issues**: 関連する Issue（`Closes #123` 形式で自動クローズ）

#### MR 作成時のルール

- **目的や変更内容を記述**: 何を変更したか、なぜ変更したかを明確に
- **レビュアーを指名**: 適切なレビュアーを指定
- **ラベルを設定**: `feature`, `bug`, `documentation` など
- **Issue との関連付け**: `Closes #123` で Issue を自動クローズ

### 9. コンフリクトが発生した場合

```bash
# rebase 中にコンフリクトが発生
git rebase origin/main
# CONFLICT メッセージが表示される

# 1. 衝突したファイルを確認
git status

# 2. ファイルをエディタで開いて修正
# <<<<<, =====, >>>>> の区切りを確認して意図した内容に修正

# 3. 修正したファイルをステージング
git add 修正したファイル

# 4. rebase を再開
git rebase --continue

# コンフリクトがすべて解消するまで繰り返す

# rebase を中断したい場合
git rebase --abort
```

### 10. 作業スペースを削除する

MR がマージされたら、作業スペースとブランチを削除します。

```bash
# メインブランチに移動
cd ../../haniwers

# メインブランチを最新状態にする
git fetch --prune
git pull

# worktree を確認
git worktree list

# worktree を削除
git worktree remove ../worktrees/feat-new-feature

# ブランチを削除
git branch -d feat-new-feature
```

## バージョン管理とリリース

### バージョンのバンプ

プロジェクトでは Commitizen を使用してセマンティックバージョニングを行います。

```bash
# バージョン確認（dry-run）
poetry run cz bump --dry-run

# バージョンをバンプしてチェンジログを更新
poetry run cz bump --changelog --check-consistency

# タグをプッシュ
git push origin --tags
```

自動的に以下が更新されます：

- `pyproject.toml:version`
- `src/haniwers/__init__.py:__version__`
- `CHANGELOG.md`

## コーディング規約

### Python スタイル

- **PEP 8** に準拠
- **Ruff** でフォーマットと静的解析
- **型ヒント**: 可能な限り使用
- **Docstring**: 公開関数・クラスには必須

### 命名規則

- 変数・関数: `snake_case`
- クラス: `PascalCase`
- 定数: `UPPER_CASE`

### コードの例

```python
from typing import Optional

class ThresholdScanner:
    """Threshold scanning functionality.

    This class provides methods for scanning threshold values
    and analyzing cosmic ray detection data.
    """

    def scan_thresholds(
        self,
        start_value: int,
        end_value: int,
        step: int = 10
    ) -> list[int]:
        """Scan threshold values within the specified range.

        Args:
            start_value: Starting threshold value
            end_value: Ending threshold value
            step: Step size for scanning (default: 10)

        Returns:
            List of scanned threshold values
        """
        # Implementation here
        pass
```

## テスト要件

- **すべての新機能にはテストを追加**
- **バグ修正には再現テストを追加**
- **カバレッジ目標: 80%以上**
- **テストは unit/integration に分類**

詳細は[テストガイドライン](./testing.md)を参照してください。

## ドキュメント要件

コードの変更に伴い、以下のドキュメントを更新してください：

- **API ドキュメント**: Docstring の更新
- **ユーザードキュメント**: 使い方の変更がある場合
- **CHANGELOG.md**: 重要な変更点の記録
- **README.md**: プロジェクト概要の変更がある場合

## 質問やサポート

わからないことがあれば、遠慮なく質問してください：

- **Issue で質問**: [GitLab Issues](https://gitlab.com/qumasan/haniwers/-/issues)
- **MR でコメント**: レビュー時にコメントで質問
- **開発者に連絡**: プロジェクトメンバーに直接連絡

---

貢献してくださるすべての方に感謝します！