開発者向けガイド

開発者向けガイド#

ゴール

haniwers のコードを理解して、測定ツールを改善・拡張しよう

このセクションは、haniwers の開発に参加したい開発者向けです。

初めての方は、まず以下を読んでください：

📋 開発に参加する前に#

  1. リポジトリをフォークまたはクローン

  2. 開発ブランチを作成

  3. 小さな変更から始める

  4. テストとドキュメントを併せて更新

詳細は 開発ガイド を参照してください。

🚀 開発環境の構築手順#

ステップ 1: リポジトリのセットアップ#

# リポジトリをクローン
git clone https://gitlab.com/qumasan/haniwers
cd haniwers

# Git worktree で開発ブランチを作成（推奨）
git worktree add ../worktrees/feature-name -b feature/feature-name

# または通常のブランチ切り替え
git branch feature/feature-name
git switch feature/feature-name

ステップ 2: 依存関係のインストール#

# 開発・ドキュメント依存関係を含めてインストール
poetry install --with docs,dev

# または uv を使用（最速）
uv sync --all-groups

ステップ 3: 環境確認#

# 依存関係ツリー確認
poetry show --tree

# haniwers のバージョン・環境情報確認
poetry run haniwers version

ステップ 4: 開発環境テスト#

# テストの実行
poetry run pytest

# コード品質チェック
poetry run ruff check .
poetry run ruff format .

🧪 開発・テスト方法#

コマンドの実行テスト#

開発環境で haniwers コマンドが正しく動作するか確認：

# サンドボックスディレクトリで実行
cd sandbox

# ヘルプ表示
poetry run haniwers --help

# 利用可能なポート確認
poetry run haniwers ports

# バージョン確認
poetry run haniwers version

# 特定のコマンドをテスト
poetry run haniwers scan --help
poetry run haniwers daq --help

ユニットテスト#

# 基本テスト実行
poetry run pytest

# カバレッジ付きテスト
poetry run pytest --cov=haniwers --cov-report=html

# 特定のテストモジュール実行
poetry run pytest tests/test_config.py -v

コード品質チェック#

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

# 静的解析
poetry run ruff check .

# 型チェック（mypy設定がある場合）
# poetry run mypy haniwers/

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

現在のモジュール構成（v0.23.1）#

haniwers/cli.py#

メインのCLIエントリーポイント：

  • Typerベースのコマンド定義

  • daq, scan, fit, vth, ports等のサブコマンド

  • ログ設定とオプション解析

haniwers/config.py#

設定管理：

  • Config, RunData, UserSettingsクラス

  • TOML設定ファイル（daq.toml, scan.toml）の読み込み

  • パス管理と環境固有設定

haniwers/daq.py#

データ取得（DAQ）：

  • シリアル通信（pyserial）による測定器制御

  • RealEventクラスによるイベントデータ構造

  • ファイル保存とタイムスタンプ管理

haniwers/threshold.py#

スレッショルド制御：

  • scan_thresholds_in_parallel: 並列スレッショルド測定

  • Countデータクラス: 測定結果の構造化

  • フィット処理とCSV出力

haniwers/dataset.py#

データ処理：

  • Runクラス: 測定データへのアクセス

  • パス管理とファイル操作

  • データフレーム変換

haniwers/preprocess.py & haniwers/postprocess.py#

データ処理パイプライン：

  • 生データの前処理とリサンプリング

  • 可視化とプロット機能

  • CSV形式への変換

現在の設計方針#

アーキテクチャ#

  • モジュールごとの責務分離

    • CLI: コマンド定義とオプション解析（cli.py）

    • DAQ: ハードウェア制御とデータ取得（daq.py）

    • 設定: TOML設定の管理（config.py）

    • データ処理: 前処理・後処理・可視化（preprocess.py, postprocess.py）

  • CLIはTyperベース

    • haniwers COMMAND [OPTIONS] 形式

    • サブコマンド: daq, scan, fit, vth, ports, run2csv

    • 統一されたログ出力とエラー処理

  • 設定ファイルによる柔軟性

    • daq.toml: データ取得設定

    • scan.toml: スレッショルドスキャン設定

    • runs.csv: 実験ラン管理

  • データフロー

    • 生データ取得 → 前処理 → CSV保存 → 可視化・解析

    • タイムスタンプベースのファイル管理

    • Pandas/Polarsによる効率的なデータ処理

開発のベストプラクティス#

コーディング規約#

  • Conventional Commits: コミットメッセージ規約の遵守

  • Ruff: フォーマットと静的解析

  • 型ヒント: 可能な限りtype hintsを使用

  • Docstring: 公開関数には説明を記載

リリース手順#

# 1. 機能開発・バグ修正
git commit -m "feat: add new feature"

# 2. バージョン管理
poetry run cz bump --dry-run  # 確認
poetry run cz bump -cc -ch    # 実行

# 3. パッケージ公開
poetry build
poetry publish --repository testpypi  # テスト
poetry publish                        # 本番

# 4. タグプッシュ
git push origin main --tags

デバッグとテスト#

  • ログレベル: --log-level DEBUG でデバッグ情報表示

  • モック: haniwers/mimic.py で擬似データ生成

  • 単体テスト: 新機能追加時はテストも併せて作成

📚 関連ドキュメント#

✅ 開発時のチェックリスト#

開発や改修を行う際は、以下を確認してください：

  • コードが Ruff フォーマットを通す（poetry run ruff format .）

  • テストが全て通る（poetry run pytest）

  • pre-commit フックが通る（poetry run pre-commit run --all-files）

  • 新機能に対応するテストを追加している

  • ドキュメント（docstring）を更新している

  • リリースノートに変更点を記載している（必要に応じて）

🤝 貢献ガイドライン#

  1. 小さな変更から始める - 大きな変更は事前にイシューで相談

  2. テストとドキュメント必須 - コードだけでなく、テストと doc も

  3. Conventional Commits - コミットメッセージ形式を遵守

  4. MR テンプレート使用 - GitLab の MR テンプレートを使用

  5. コードレビュー - CI が通ったら、他の開発者のレビューを待つ

詳細は 開発ガイド を参照してください。

目次