パッケージ概要

このモノレポには、@qwen-code/qwen-code と @qwen-code/qwen-code-core の2つの主要パッケージが含まれています。

`@qwen-code/qwen-code`

これは Qwen Code のメインパッケージです。ユーザーインターフェース、コマンドの解析、その他のユーザー向け機能を担当します。

このパッケージが公開されると、単一の実行可能ファイルにバンドルされます。このバンドルには、@qwen-code/qwen-code-core を含むすべての依存関係が含まれます。つまり、ユーザーが npm install -g @qwen-code/qwen-code でインストールするか、npx @qwen-code/qwen-code で直接実行するかに関わらず、この単一の自己完結型実行ファイルを使用していることになります。

`@qwen-code/qwen-code-core`

このパッケージには CLI のコアロジックが含まれています。設定されたプロバイダーへの API リクエストの送信、認証の処理、ローカルキャッシュの管理を担当します。

このパッケージはバンドルされません。公開時には、独自の依存関係を持つ標準的な Node.js パッケージとして公開されます。これにより、必要に応じて他のプロジェクトでスタンドアロンパッケージとして使用できます。dist フォルダ内のすべてのトランスパイル済み JS コードがパッケージに含まれます。

リリースプロセス

このプロジェクトでは、すべてのパッケージが正しくバージョン管理され、公開されるように構造化されたリリースプロセスを採用しています。このプロセスは可能な限り自動化されるように設計されています。

リリース方法

リリースは release.yml GitHub Actions ワークフローを通じて管理されます。パッチまたはホットフィックスの手動リリースを実行するには：

リポジトリの Actions タブに移動します。
リストから Release ワークフローを選択します。
Run workflow ドロップダウンボタンをクリックします。
必須の入力項目を入力します：
- Version: リリースする正確なバージョン（例：v0.2.1）。
- Ref: リリース元のブランチまたはコミット SHA（デフォルトは main）。
- Dry Run: 公開せずにワークフローをテストする場合は true のままにし、実際のリリースを実行する場合は false に設定します。
Run workflow をクリックします。

リリースタイプ

このプロジェクトは複数のリリースタイプをサポートしています：

安定版リリース

本番環境で使用する定期的な安定版リリース。

プレビューリリース

今後の機能に早期にアクセスするためのプレビューリリース。毎週火曜日 23:59 UTC に公開されます。

ナイトリーリリース

最先端の開発テストのためのナイトリーリリース。毎日 00:00 UTC に公開されます。

自動リリーススケジュール

Nightly: 毎日 00:00 UTC
Preview: 毎週火曜日 23:59 UTC
Stable: メンテナーがトリガーする手動リリース

各リリースタイプの使用方法

各タイプの最新バージョンをインストールするには：


# Stable (default)
npm install -g @qwen-code/qwen-code
 
# Preview
npm install -g @qwen-code/qwen-code@preview
 
# Nightly
npm install -g @qwen-code/qwen-code@nightly

リリースプロセスの詳細

スケジュールされたリリースと手動リリースの両方で、以下の手順が実行されます：

指定されたコードをチェックアウトします（main ブランチの最新または特定のコミット）。
すべての依存関係をインストールします。
preflight チェックと統合テストの完全なスイートを実行します。
すべてのテストに成功した場合、リリースタイプに基づいて適切なバージョン番号を計算します。
パッケージをビルドし、適切な dist-tag を付けて npm に公開します。
そのバージョンの GitHub Release を作成します。

エラー処理

リリースワークフローのいずれかのステップで失敗した場合、リポジトリに bug ラベルとタイプ固有の失敗ラベル（例：nightly-failure、preview-failure）が付いた新しい Issue が自動的に作成されます。Issue にはデバッグを容易にするため、失敗したワークフロー実行へのリンクが含まれます。

リリースの検証

新しいリリースをプッシュした後、パッケージが期待通りに動作することを確認するためにスモークテストを実行する必要があります。これは、パッケージをローカルにインストールし、正しく機能していることを確認するための一連のテストを実行することで実施できます。

rc または dev タグを使用していない場合、プッシュが期待通りに機能したことを検証するには npx -y @qwen-code/qwen-code@latest --version を実行します。
適切にプッシュされたタグを検証するには npx -y @qwen-code/qwen-code@<release tag> --version を実行します。
ローカル環境で破壊的な操作が行われます npm uninstall @qwen-code/qwen-code && npm uninstall -g @qwen-code/qwen-code && npm cache clean --force && npm install @qwen-code/qwen-code@<version>
パッケージが期待通りに動作していることを確認するため、いくつかの LLM コマンドとツールを実行する基本的なスモークテストの実施を推奨します。今後、この手順はより詳細に文書化する予定です。

バージョン変更をマージするかどうかの判断基準

現在のコミットまたは過去のコミットからパッチまたはホットフィックスリリースを作成する上記のパターンでは、リポジトリは以下の状態になります：

タグ（vX.Y.Z-patch.1）：このタグは、リリースを意図した安定版コードを含む main 上の元のコミットを正しく指しています。これは非常に重要です。このタグをチェックアウトした誰でも、公開された正確なコードを取得できます。
ブランチ（release-vX.Y.Z-patch.1）：このブランチには、タグ付けされたコミットの上に1つの新しいコミットが含まれています。その新しいコミットには、package.json（および package-lock.json などの関連ファイル）のバージョン番号の変更のみが含まれています。

この分離は適切です。マージを決定するまで、リリース固有のバージョンアップによって main ブランチの履歴が汚れるのを防ぎます。

これは重要な判断であり、リリースの性質に完全に依存します。

安定版パッチおよびホットフィックスのマージバック

安定版パッチまたはホットフィックスリリースの場合、ほぼ常に release-<tag> ブランチを main にマージバックする必要があります。

理由：主な理由は、main の package.json のバージョンを更新するためです。古いコミットから v1.2.1 をリリースしても、バージョンアップをマージバックしない場合、main ブランチの package.json は依然として "version": "1.2.0" のままになります。次の機能リリース（v1.3.0）の作業を開始する開発者は、誤った古いバージョン番号を持つコードベースからブランチを作成することになります。これにより混乱が生じ、後で手動でのバージョンアップが必要になります。
手順：release-v1.2.1 ブランチが作成され、パッケージが正常に公開された後、release-v1.2.1 を main にマージするためのプルリクエストを作成する必要があります。この PR には「chore: bump version to v1.2.1」という1つのコミットのみが含まれます。これはクリーンでシンプルな統合であり、main ブランチを最新のリリースバージョンと同期させ続けます。

プレリリース（RC、Beta、Dev）のマージバックは不要

通常、プレリリース用のリリースブランチを main にマージバックする必要はありません。

理由：プレリリースバージョン（例：v1.3.0-rc.1、v1.3.0-rc.2）は、定義上安定しておらず一時的なものです。リリース候補版の一連のバージョンアップで main ブランチの履歴を汚したくはありません。main の package.json は RC ではなく、最新の安定版リリースバージョンを反映しているべきです。
手順：release-v1.3.0-rc.1 ブランチが作成され、npm publish --tag rc が実行されると、ブランチの役割は完了します。単純に削除して構いません。RC のコードはすでに main（または機能ブランチ）上にあるため、機能コードが失われることはありません。リリースブランチはバージョン番号のための一時的な手段に過ぎませんでした。

ローカルテストと検証：パッケージングおよび公開プロセスの変更

NPM への実際の公開や公開 GitHub Release の作成なしにリリースプロセスをテストする必要がある場合、GitHub UI からワークフローを手動でトリガーできます。

リポジトリの Actions タブに移動します。
「Run workflow」ドロップダウンをクリックします。
dry_run オプションをチェックしたまま（true）にします。
「Run workflow」ボタンをクリックします。

これによりリリースプロセス全体が実行されますが、npm publish と gh release create のステップはスキップされます。ワークフローログを確認し、すべてが期待通りに動作していることを確認できます。

パッケージングおよび公開プロセスへの変更をコミットする前に、ローカルでテストすることが重要です。これにより、パッケージが正しく公開され、ユーザーがインストールした際に期待通りに動作することが保証されます。

変更を検証するには、公開プロセスのドライランを実行できます。これにより、パッケージを npm レジストリに実際に公開することなく、公開プロセスをシミュレートします。


npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME="thename" npm run publish:npm --dry-run

このコマンドは以下の処理を行います：

すべてのパッケージをビルドします。
すべての prepublish スクリプトを実行します。
npm に公開されるパッケージの tarball を作成します。
公開されるパッケージの概要を出力します。

生成された tarball を検査し、正しいファイルが含まれていること、および package.json ファイルが正しく更新されていることを確認できます。tarball は各パッケージディレクトリのルートに作成されます（例：packages/cli/qwen-code-0.1.6.tgz）。

ドライランを実行することで、パッケージングプロセスへの変更が正しく、パッケージが正常に公開されることを確信できます。

リリースプロセスの詳細解説

リリースプロセスの主な目的は、packages/ ディレクトリからソースコードを取得してビルドし、プロジェクトのルートにある一時的な dist ディレクトリ内にクリーンで自己完結型のパッケージを組み立てることです。実際に NPM に公開されるのは、この dist ディレクトリです。

主なステージは以下の通りです：

ステージ 1：リリース前の健全性チェックとバージョニング

処理内容：ファイルを移動する前に、プロジェクトが正常な状態であることを確認します。これには、テスト、リンティング、型チェックの実行（npm run preflight）が含まれます。ルート package.json と packages/cli/package.json のバージョン番号が新しいリリースバージョンに更新されます。
理由：高品質で動作するコードのみがリリースされることを保証します。バージョニングは、新しいリリースを示す最初のステップです。

ステージ 2：ソースコードのビルド

処理内容：packages/core/src と packages/cli/src の TypeScript ソースコードが JavaScript にコンパイルされます。
ファイルの移動：
- packages/core/src/*/.ts -> コンパイル先 -> packages/core/dist/
- packages/cli/src/*/.ts -> コンパイル先 -> packages/cli/dist/
理由：開発中に記述された TypeScript コードは、Node.js で実行可能なプレーンな JavaScript に変換する必要があります。cli パッケージが依存しているため、core パッケージが最初にビルドされます。

ステージ 3：最終的な公開可能パッケージのバンドルと組み立て

これは、ファイルが移動され、公開用の最終状態に変換される最も重要なステージです。このプロセスでは、最終パッケージを作成するために最新のバンドリング技術が使用されます。

バンドルの作成：
- 処理内容：prepare-package.js スクリプトが dist ディレクトリ内にクリーンな配布パッケージを作成します。
- 主な変換：
  - README.md と LICENSE を dist/ にコピー
  - 国際化対応のため locales フォルダをコピー
  - 必要な依存関係のみを含む配布用のクリーンな package.json を作成
  - 配布依存関係を最小限に維持（ランタイム依存関係はバンドルしない）
  - node-pty のオプション依存関係を維持
JavaScript バンドルの作成：
- 処理内容：packages/core/dist と packages/cli/dist の両方のビルド済み JavaScript が、esbuild を使用して単一の実行可能 JavaScript ファイルにバンドルされます。
- ファイルの場所：dist/cli.js
- 理由：必要なアプリケーションコードをすべて含む単一の最適化されたファイルが作成されます。インストール時の複雑な依存関係解決の必要性を排除することで、パッケージが簡素化されます。
静的ファイルおよびサポートファイルのコピー：
- 処理内容：ソースコードの一部ではないが、パッケージが正しく動作するため、または適切に説明するために必要な必須ファイルが dist ディレクトリにコピーされます。
- ファイルの移動：
  - README.md -> dist/README.md
  - LICENSE -> dist/LICENSE
  - locales/ -> dist/locales/
  - ベンダーファイル -> dist/vendor/
- 理由：
  - README.md と LICENSE は、すべての NPM パッケージに含めるべき標準ファイルです。
  - locales は国際化機能をサポートします
  - ベンダーファイルには必要なランタイム依存関係が含まれています

ステージ 4：NPM への公開

処理内容：ルート dist ディレクトリ内から npm publish コマンドが実行されます。
理由：dist ディレクトリ内から npm publish を実行することで、ステージ 3 で慎重に組み立てたファイルのみが NPM レジストリにアップロードされます。これにより、ソースコード、テストファイル、開発設定が誤って公開されるのを防ぎ、ユーザー向けにクリーンで最小限のパッケージを提供します。

このプロセスにより、最終的に公開されるアーティファクトは、開発ワークスペースの単純なコピーではなく、プロジェクトの目的に合わせて構築されたクリーンで効率的な表現であることが保証されます。

NPM Workspaces

このプロジェクトでは、このモノレポ内のパッケージを管理するために NPM Workspaces を使用しています。プロジェクトのルートから複数のパッケージにわたって依存関係を管理し、スクリプトを実行できるため、開発が簡素化されます。

動作原理

ルートの package.json ファイルで、このプロジェクトのワークスペースを定義しています：


{
  "workspaces": ["packages/*"]
}

これにより、packages ディレクトリ内のすべてのフォルダが、ワークスペースの一部として管理される個別のパッケージであることが NPM に伝えられます。

Workspaces の利点

依存関係管理の簡素化：プロジェクトのルートから npm install を実行すると、ワークスペース内のすべてのパッケージの依存関係がインストールされ、相互にリンクされます。これにより、各パッケージのディレクトリで個別に npm install を実行する必要がなくなります。
自動リンク：ワークスペース内のパッケージは相互に依存できます。npm install を実行すると、NPM がパッケージ間に自動的にシンボリックリンクを作成します。これにより、あるパッケージに変更を加えると、その変更が依存している他のパッケージですぐに利用可能になります。
スクリプト実行の簡素化：--workspace フラグを使用して、プロジェクトのルートから任意のパッケージのスクリプトを実行できます。例えば、cli パッケージの build スクリプトを実行するには、npm run build --workspace @qwen-code/qwen-code を実行します。