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

DuoKey PQCスキャナーへのコントリビューション

DuoKey PQCスキャナー開発へのコントリビューションガイド

適用対象:

Rust DevelopmentOpen SourceCommunity

DuoKey PQCスキャナーへのコントリビューションにご関心をお寄せいただきありがとうございます！このガイドは、開発を始めるのに役立ちます。

開発環境のセットアップ

前提条件

前提条件

• Rust: stable ツールチェーン（最新バージョンを推奨）
• Git: バージョン管理用
• IDE: rust-analyzer 拡張機能を備えた VS Code（推奨）

リポジトリのクローン

git clone https://github.com/duokey/dke-scanner-agent.git
cd dke-scanner-agent

依存関係のインストール

# Install Rust if not already installed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Update Rust to latest stable
rustup update stable

# Install development tools
rustup component add rustfmt clippy

# Install cargo-watch for development
cargo install cargo-watch

# Install cargo-audit for security checks
cargo install cargo-audit

プロジェクトのビルド

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run -- agent

プロジェクト構成

ハイレベルでは、プロジェクトは以下の機能領域に整理されています。

領域	内容
CLI	コマンドラインインターフェースおよびコマンドディスパッチ
Core	コアスキャンロジック（暗号検出、リスクスコアリング、X.509 操作、およびアルゴリズムデータベース）
Scanners	スキャンモード（エージェント、ファイルシステム、ドメイン、ネットワーク）
Parsers	サポートされている証明書およびキーストア形式の形式パーサー
Output	サポートされているレポート形式の出力フォーマッター
Utilities	ロギングやエラー処理などの共有ヘルパー
Tests	統合テスト
Benchmarks	パフォーマンスベンチマーク
Examples	使用例

開発ワークフロー

1

機能ブランチの作成

git checkout -b feature/my-new-feature

2

変更の実施

# Edit code in your preferred editor

# Format code
cargo fmt

# Run clippy for lints
cargo clippy -- -D warnings

# Run tests
cargo test

# Run specific test
cargo test test_rsa_detection

3

ローカルでのテスト

# Run all tests
cargo test --all

# Run integration tests
cargo test --test '*'

# Run with coverage (requires cargo-tarpaulin)
cargo install cargo-tarpaulin
cargo tarpaulin --out Html

# Run benchmarks
cargo bench

4

変更のコミット

git add .
git commit -m "feat: add new feature"

5

プッシュと PR の作成

git push origin feature/my-new-feature
# Create pull request on GitHub

コーディング標準

Rust スタイルガイド

Rust API ガイドライン に従ってください。関数や型には説明的で自己説明的な名前を優先し、すべての公開項目にはその目的を説明するドキュメントコメントを付けてください。省略された難解な名前や、ドキュメント化されていない公開 API は避けてください。

コードフォーマット

デフォルト設定で rustfmt を使用します。

cargo fmt

プロジェクトの rustfmt.toml は 2021 エディションを固定し、最大行幅を 100 文字に設定し、デフォルトの small-heuristics 設定を使用します。

リンティング

リント（静的解析）には clippy を使用します。

cargo clippy -- -D warnings

ドキュメント

すべての公開 API にドキュメントコメントを付けてください。良いドキュメントコメントは、その項目が何をするかを要約し、該当する場合は標準的なセクション（Arguments、Returns、Errors、Examples）を含みます。たとえば、ファイルシステムスキャン関数は、受け取るディレクトリパスと再帰フラグ、返す検出結果、エラー条件（パスの欠落や権限不足など）、および短い使用例を記述すべきです。

テスト

ユニットテストは、それがカバーするコードと同じファイル内のテストモジュールに配置してください。各テストは 1 つの動作を検証し、特定の結果をアサートすべきです。たとえば、2048 ビットの RSA 鍵が期待される量子リスクスコアを受け取ることの検証や、無効な証明書の分析がパニックではなくエラーを返すことの検証などです。

パフォーマンス

セキュリティ

重要

依存関係に既知の脆弱性が存在しないことを確認するため、すべてのリリース前にセキュリティ監査を実行してください。

セキュリティ監査

cargo audit

# Fix vulnerabilities
cargo audit fix

Unsafe コード

警告

絶対に必要な場合を除き、unsafe コードは避けてください。必要な場合は、なぜ必要なのかを記述し、安全性の証明を提供し、広範なテストを追加し、複数のメンテナーによるレビューを依頼してください。

unsafe が避けられない場合、そのような各ブロックには、その操作が健全である理由を正確に説明する # Safety ドキュメントセクションを付ける必要があります。

エラー処理

アプリケーションエラーには anyhow を、ライブラリエラーには thiserror を使用してください。ライブラリには明示的で型付けされたエラーバリアント（たとえば、証明書解析の失敗、I/O エラー、無効なアルゴリズムエラー）を定義し、各失敗しうる操作に説明的なコンテキストを付けて、失敗をその発生源まで容易に追跡できるようにしてください。

ロギング

構造化ロギングには tracing を使用してください。主要な操作が開始されるとき（ディレクトリスキャンの開始など）には info レベルのメッセージを、回復可能な問題が発生したとき（アクセスできないディレクトリエントリなど）には warning を、より細かい進捗の詳細には debug レベルのメッセージを発行してください。

コミットメッセージ規約

Conventional Commits に従ってください。

<type>(<scope>): <subject>

<body>

<footer>

タイプ	説明
feat	新機能
fix	バグ修正
docs	ドキュメントの変更
style	コードスタイルの変更（フォーマット）
refactor	コードのリファクタリング
perf	パフォーマンスの改善
test	テストの追加
chore	メンテナンス作業

プルリクエストのプロセス

1

PR の作成

明確なタイトルと説明を付けた PR を作成します。

2

関連 Issue のリンク

"Closes #123" を使用して関連 Issue をリンクします。

3

テストの合格の確認

すべての CI チェックがグリーンである必要があります。

4

レビューの依頼

コードレビューのために関連するメンテナーをタグ付けします。

5

フィードバックへの対応

依頼された変更を速やかに行います。

6

コミットのスカッシュ

マージ前に、メンテナーから依頼された場合に行います。

リリースプロセス

1

バージョンの更新

パッケージマニフェスト内のプロジェクトバージョンを更新します。

2

Changelog の更新

CHANGELOG.md をリリースノートで更新します。

3

リリースタグの作成

git tag v1.0.0

4

タグのプッシュ

git push --tags

5

リリースのビルド

cargo build --release

6

公開

cargo publish

コミュニティ

GitHub コミュニケーションチャネル

• GitHub Issues: バグ報告と機能リクエスト
• GitHub Discussions: 一般的な質問とディスカッション
• Discord: リアルタイムチャット（リンクは README に記載）

Code 行動規範

私たちは Rust 行動規範 に従います。すべてのやり取りにおいて、敬意を持ち、包括的で、建設的であってください。

ライセンス

コントリビューションを行うことにより、あなたのコントリビューションがプロジェクトと同じライセンスの下でライセンスされることに同意したものとみなされます（LICENSE ファイルを参照）。

ご質問は？

ご質問がある場合は、次を行ってください。

1. 既存のドキュメントを確認する
2. GitHub の Issue を検索する
3. GitHub Discussions で質問する
4. メンテナーに連絡する

ヒント

PQCスキャナーへのコントリビューションをありがとうございます！どんなに小さくても、すべてのコントリビューションがプロジェクトをより良くするのに役立ちます。