Skip to Content
デベロッパーガイド貢献ガイド

コントリビューション方法

このプロジェクトへのパッチおよびコントリビューションを歓迎します。

コントリビューションの流れ

コードレビュー

プロジェクトメンバーによる提出を含め、すべての提出物はレビューを必要とします。この目的のために、GitHub のプルリクエスト  を使用します。

プルリクエストに関するガイドライン

PR のレビューおよびマージを迅速に行えるよう、以下のガイドラインに従ってください。これらの基準を満たさない PR はクローズされる場合があります。

1. 既存の課題へのリンク

すべてのプルリクエスト（PR）は、当プロジェクトの課題追跡システムに登録済みの課題にリンクする必要があります。これにより、コードを記述する前に、変更内容が十分に議論され、プロジェクトの目標と整合していることを保証します。

  • バグ修正の場合： PR は対応するバグ報告の課題にリンクしてください。
  • 新機能追加の場合： PR は、メンテナーによって承認済みの機能要望または提案の課題にリンクしてください。

ご自身の変更に対応する課題が存在しない場合は、まず課題を新規作成し、コーディングを開始する前にフィードバックを待ってください。

2. 小さく、焦点を絞った PR を心がける

単一の課題を解決する、あるいは単一の自己完結型の機能を追加する、小さなアトミックな PR を推奨しています。

  • 推奨： 特定の 1 つのバグを修正する、あるいは特定の 1 つの機能を追加する PR を作成する。
  • 避ける： 複数の無関係な変更（例：バグ修正、新機能追加、リファクタリング）を 1 つの PR にまとめて含めない。

大規模な変更は、個別にレビュー・マージ可能な、一連の小さな論理的な PR に分割してください。

3. 作業中のプルリクエストにはドラフト PR を使用する

作業の早期段階でフィードバックを得たい場合は、GitHub の ドラフトプルリクエスト 機能をご利用ください。これにより、メンテナーに対して、そのプルリクエストは正式なレビューにはまだ準備ができていないが、議論および初期のフィードバックは歓迎するという意図を明示できます。

4. すべてのチェックが通過していることを確認する

プルリクエストを送信する前に、npm run preflight を実行して、すべての自動チェックが通過していることを確認してください。このコマンドは、すべてのテスト、リンティング、およびその他のスタイルチェックを実行します。

5. ドキュメントを更新する

プルリクエストがユーザー向けの変更（例：新しいコマンドの追加、フラグの変更、動作の変更など）を含む場合、/docs ディレクトリ内の関連するドキュメントも必ず更新してください。

6. 明確なコミットメッセージと適切なプルリクエスト（PR）説明を記述する

プルリクエスト（PR）には、明確で説明的なタイトルと、変更内容を詳細に記述した説明文を付けてください。コミットメッセージには、Conventional Commits  標準に従ってください。

  • 適切な PR タイトルの例： feat(cli): 'config get' コマンドに --json フラグを追加
  • 不適切な PR タイトルの例： いくつかの変更を行いました

PR の説明文では、変更の「理由（why）」を説明し、関連するイシューへのリンク（例：Fixes #123）を記載してください。

開発環境のセットアップとワークフロー

このセクションでは、本プロジェクトの開発環境のビルド、変更、および理解に関する手順を貢献者向けに説明します。

開発環境のセットアップ

前提条件:

  1. Node.js:
    • 開発時: Node.js ~20.19.0 を使用してください。この特定のバージョンは、上流の開発依存関係の問題により必須です。nvm  などのツールを用いて Node.js のバージョンを管理できます。
    • 本番時: CLI を本番環境で実行する場合、Node.js >=20 の任意のバージョンで構いません。
  2. Git

ビルド手順

リポジトリをクローンするには、以下のコマンドを実行します:

git clone https://github.com/QwenLM/qwen-code.git # またはフォーク先の URL
cd qwen-code

package.json に定義された依存関係およびルートの依存関係をインストールするには:

npm install

プロジェクト全体（すべてのパッケージ）をビルドするには:

npm run build

このコマンドは通常、TypeScript を JavaScript にコンパイルし、アセットをバンドルして、パッケージを実行可能な状態に準備します。ビルド時に実行される処理の詳細については、scripts/build.js および package.json 内のスクリプトを参照してください。

サンドボックスの有効化

サンドボックス の使用は強く推奨されており、最低限 ~/.env に QWEN_SANDBOX=true を設定し、サンドボックスプロバイダー（例：macOS Seatbelt、docker、または podman）が利用可能である必要があります。詳細については、サンドボックス を参照してください。

qwen-code CLI ユーティリティおよびサンドボックスコンテナの両方をビルドするには、ルートディレクトリから build:all を実行します：

npm run build:all

サンドボックスコンテナのビルドをスキップする場合は、代わりに npm run build を使用できます。

実行

ソースコードから Qwen Code アプリケーションを起動するには（ビルド後）、ルートディレクトリから以下のコマンドを実行します：

npm start

qwen-code フォルダ外でソースビルドを実行したい場合は、npm link path/to/qwen-code/packages/cli を利用して qwen-code コマンドで実行できます（詳しくは ドキュメント  を参照）。

テストの実行

このプロジェクトには、単体テストと統合テストの 2 種類のテストが含まれています。

単体テスト

プロジェクトの単体テストスイートを実行するには、以下のコマンドを実行します：

npm run test

このコマンドは、packages/core および packages/cli ディレクトリ内のテストを実行します。変更を送信する前に、すべてのテストが成功することを確認してください。より包括的なチェックを行う場合は、npm run preflight を実行することを推奨します。

統合テスト

統合テストは、Qwen Code のエンドツーエンド機能を検証するために設計されています。これらのテストは、デフォルトの npm run test コマンドの一部として実行されません。

統合テストを実行するには、以下のコマンドを使用します：

npm run test:e2e

統合テストフレームワークに関する詳細情報については、統合テストのドキュメント を参照してください。

リンティングと事前チェック

コード品質とフォーマットの一貫性を確保するため、事前チェックを実行します。

npm run preflight

このコマンドは、プロジェクトの package.json で定義された ESLint、Prettier、すべてのテストおよびその他のチェックを実行します。

ProTip

リポジトリをクローンした直後に、コミットが常にクリーンであることを保証するための Git の pre-commit フックファイルを作成しましょう。

echo "
 
# npm build を実行し、エラーを確認
if ! npm run preflight; then
  echo "npm build に失敗しました。コミットを中止します。"
  exit 1
fi
" > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

フォーマット

プロジェクト内のコードを個別にフォーマットするには、ルートディレクトリから以下のコマンドを実行します。

npm run format

このコマンドは Prettier を使用して、プロジェクトのスタイルガイドに従ってコードをフォーマットします。

リンティング

プロジェクト内のコードを個別にリンティングするには、ルートディレクトリから以下のコマンドを実行します。

npm run lint

コーディング規約

  • 既存のコードベース全体で使用されているコーディングスタイル、パターン、および規約に従ってください。
  • インポート: インポートパスに特に注意してください。本プロジェクトでは、パッケージ間の相対インポートを制限するために ESLint を使用しています。

プロジェクト構成

  • packages/: プロジェクトの個別のサブパッケージが格納されています。
    • cli/: コマンドラインインターフェース。
    • core/: Qwen Code のコアバックエンドロジック。
  • docs/: プロジェクトのすべてのドキュメントが格納されています。
  • scripts/: ビルド、テスト、開発タスク用のユーティリティスクリプト。

より詳細なアーキテクチャについては、docs/architecture.md を参照してください。

ドキュメント開発

このセクションでは、ドキュメントをローカルで開発・プレビューする方法について説明します。

前提条件

  1. Node.js（バージョン 18+）がインストール済みであることを確認してください。
  2. npm または yarn が利用可能であることを確認してください。

ドキュメントサイトをローカルでセットアップする

ドキュメントの作業および変更内容のローカルプレビューを行うには、以下の手順に従ってください。

  1. docs-site ディレクトリに移動します：

    cd docs-site

  2. 依存関係をインストールします：

    npm install

  3. メインの docs ディレクトリからドキュメントコンテンツをリンクします：

    npm run link

    このコマンドは、../docs から docs-site プロジェクト内の content へシンボリックリンクを作成します。これにより、Next.js サイトでドキュメントコンテンツを提供できるようになります。

  4. 開発サーバーを起動します：

    npm run dev

  5. ブラウザで http://localhost:3000  を開き、変更を加えるたびにライブ更新されるドキュメントサイトを確認します。

メインの docs ディレクトリ内のドキュメントファイルに対する変更は、ドキュメントサイトに即座に反映されます。

デバッグ

VS Code:

  1. CLI を実行して、F5 キーで VS Code 上で対話的にデバッグします。
  2. ルートディレクトリから CLI をデバッグモードで起動します： 
    npm run debug
    このコマンドは packages/cli ディレクトリ内で node --inspect-brk dist/index.js を実行し、デバッガーが接続されるまで実行を一時停止します。その後、Chrome ブラウザで chrome://inspect を開き、デバッガーに接続できます。
  3. VS Code では、「Attach」（接続）用の起動設定（.vscode/launch.json 内に定義）を使用します。

あるいは、「Launch Program」（プログラムの起動）設定を VS Code で使用して、現在開いているファイルを直接起動することもできますが、一般的には F5 キーによる起動が推奨されます。

サンドボックスコンテナ内でブレークポイントを有効にするには、以下のコマンドを実行します：

DEBUG=1 qwen-code

注意: プロジェクトの .env ファイルに DEBUG=true が設定されていても、自動除外のため qwen-code には影響しません。qwen-code 固有のデバッグ設定は、.qwen-code/.env ファイルに記述してください。

React DevTools

CLI の React ベースの UI をデバッグするには、React DevTools を使用できます。CLI のインターフェースに使用されているライブラリ Ink は、React DevTools バージョン 4.x と互換性があります。

  1. Qwen Code アプリケーションを開発モードで起動します：

    DEV=true npm start

  2. React DevTools バージョン 4.28.5（または最新の互換性のある 4.x バージョン）をインストール・実行します：

    グローバルにインストールする場合：

    npm install -g react-devtools@4.28.5
react-devtools

    または、npx を使って直接実行することもできます：

    npx react-devtools@4.28.5

    実行中の CLI アプリケーションが、React DevTools に自動的に接続されます。

サンドボックス

未定

手動でのパブリッシュ

各コミットに対して、内部レジストリへアーティファクトを公開しています。ただし、ローカルで手動でビルドを作成する必要がある場合は、以下のコマンドを実行してください：

npm run clean
npm install
npm run auth
npm run prerelease:dev
npm publish --workspaces
Last updated on
ロードマップTypeScript SDK