よくある質問（開発者向け）

よくある質問（開発者向け）#

開発時によくある質問と回答をまとめています。

環境セットアップ#

Q: poetry shell が非推奨と聞きましたが、どうすればいいですか？#

A: Poetry 2.0+ では poetry shell の代わりに以下を使用してください：

# コマンドを直接実行
poetry run <command>

# または仮想環境をアクティベート
poetry env activate

poetry shell は将来のバージョンで削除される予定です。

Q: Poetry のインストールに失敗します#

A: pipx または uv を使用してインストールしてください：

# pipx を使用（推奨）
pipx install poetry

# または uv を使用
pipx install uv
uv tool install poetry

システムのPythonに直接インストールするのは避けてください。

Q: 依存関係のインストール中にエラーが発生します#

A: 以下を試してください：

# キャッシュをクリア
poetry cache clear pypi --all

# 依存関係を再インストール
poetry install --with docs,dev

それでも解決しない場合は、poetry.lock を削除して再生成してください：

rm poetry.lock
poetry install --with docs,dev

テスト#

Q: テストを実行するとエラーが出ます#

A: 以下を確認してください：

  1. 依存関係のインストール:

    poetry install --with dev

  2. 正しいディレクトリで実行:

    # プロジェクトルートで実行
poetry run pytest

  3. 特定のバージョンのみテスト:

    # v1のみ
poetry run pytest tests/v1

# v0をスキップ
poetry run pytest -m "not v0"

Q: カバレッジレポートを生成するには？#

A: 以下のコマンドを使用してください：

# ターミナルに表示
poetry run pytest --cov=haniwers.v0 --cov=haniwers.v1 --cov-report=term

# HTMLレポートを生成
poetry run pytest --cov=haniwers.v0 --cov=haniwers.v1 --cov-report=html

# ブラウザで htmlcov/index.html を開く

Q: テストが遅すぎます。速くする方法は？#

A: 並列実行を使用してください：

# pytest-xdist を使用
poetry run pytest -n auto

# 特定のマーカーのみ実行
poetry run pytest -m "not slow"

コミットとマージリクエスト#

Q: Conventional Commits の形式がよくわかりません#

A: Commitizen を使用すれば対話的に作成できます：

git add <files>
cz c

または、以下の形式に従ってください：

<type>(<scope>): <description>

[optional body]

[optional footer]

タイプ:

  • feat: 新機能

  • fix: バグ修正

  • docs: ドキュメント

  • test: テスト

  • refactor: リファクタリング

例:

feat(daq): add parallel threshold scanning
fix(config): handle missing TOML sections
docs(readme): update installation instructions

Q: pre-commit フックに失敗します#

A: フックを手動で実行して問題を確認してください：

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

# 特定のフックのみ実行
poetry run pre-commit run ruff --all-files

自動修正されるものもあるので、再度 git add してコミットしてください。

Q: MR を作成したいのですが、どうすればいいですか？#

A: glab CLI を使用するのが最も簡単です：

# glab をインストール（初回のみ）
# macOS: brew install glab
# Linux: https://gitlab.com/gitlab-org/cli

# MR を作成
glab mr create --target-branch main --template draft

または、git push 後にターミナルに表示されるリンクをクリックしてください。

Q: rebase でコンフリクトが発生しました#

A: 以下の手順で解決してください：

  1. コンフリクトファイルを確認:

    git status

  2. ファイルを編集して修正: エディタで <<<<<<<, =======, >>>>>>> の区切りを探して修正

  3. ステージングしてrebaseを続行:

    git add <fixed-files>
git rebase --continue

  4. 中断したい場合:

    git rebase --abort

デバッグ#

Q: デバッグ情報を表示するには？#

A: ログレベルを DEBUG に設定してください：

haniwers --log-level DEBUG <command>

# 例
haniwers --log-level DEBUG daq --port /dev/ttyUSB0

Q: シリアルポートが見つかりません#

A: 利用可能なポートを確認してください：

# ポート一覧を表示
haniwers ports

# Linux/macOS の場合
ls /dev/tty*

# 権限を確認（Linux）
sudo usermod -a -G dialout $USER
# ログアウト・ログインが必要

Q: ハードウェアなしでテストできますか？#

A: はい、モックDAQを使用できます：

# v0: mimic モジュールを使用
# v1: mocker デバイスを使用

# コード例
from haniwers.v1.daq.mocker import MockDevice
device = MockDevice()

アーキテクチャ#

Q: v0 と v1 の違いは何ですか？#

A:

v0:

  • シンプルで実証済み

  • プロダクション対応

  • すべての基本機能を提供

v1:

  • モダンなアーキテクチャ

  • より良いテスト容易性

  • Pydantic による設定検証

  • Loguru による構造化ロギング

詳細はアーキテクチャドキュメントを参照してください。

Q: どちらのバージョンを使うべきですか？#

A:

新機能を追加する場合:

  • v1 に追加（推奨）

  • v1 はモダンで拡張しやすい

バグ修正の場合:

  • 該当するバージョンを修正

  • 必要に応じて両方を修正

新規ユーザー:

  • v0 を使用（デフォルト、haniwers コマンド）

  • 安定性が高い

Q: v1 はいつメインになりますか？#

A: v1 が十分に成熟し、v0 のすべての機能を提供できるようになったら、メインになります。現在は段階的に機能を追加中です。

ドキュメント#

Q: ドキュメントをローカルでプレビューするには？#

A:

# ライブリロード付きプレビュー
task livehtml

# または
cd docs
poetry run make livehtml

# ブラウザで http://localhost:8000 を開く

Q: API ドキュメントが自動生成されません#

A: autodoc2 の設定を確認してください：

# Sphinx ビルドを実行
cd docs
poetry run sphinx-build -b html . _build/html

# エラーメッセージを確認

conf.py の autodoc2_packages が正しく設定されているか確認してください。

Q: ドキュメントのビルドに警告が出ます#

A:

# 警告を詳細表示
cd docs
poetry run sphinx-build -W -b html . _build/html

# -W: 警告をエラーとして扱う

リンク切れや構文エラーを修正してください。

その他#

Q: バージョンをバンプするには？#

A: Commitizen を使用してください：

# 確認（dry-run）
poetry run cz bump --dry-run

# 実行
poetry run cz bump --changelog --check-consistency

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

Q: PyPI にパッケージを公開するには？#

A:

# ビルド
poetry build

# TestPyPI でテスト
poetry publish --repository testpypi

# 本番
poetry publish

API トークンが必要です。プロジェクトメンテナーに連絡してください。

Q: git worktree のメリットは？#

A:

  • ブランチ間の切り替えが高速: ディレクトリを変更するだけ

  • 並行開発が容易: 複数のブランチで同時作業

  • git stash 不要: 作業内容が隔離されている

  • クリーンな環境: ブランチごとに独立

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

他に質問がありますか？

GitLab Issues で質問するか、プロジェクトメンバーに連絡してください。

目次