パッケージ概要

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

`@qwen-code/qwen-code`

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

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

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

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

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

リリースプロセス

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

リリース方法

リリースは、release.yml GitHub Actions ワークフローを通じて管理されます。パッチまたはホットフィックスの手動リリースを実行するには、以下の手順に従ってください。

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

リリースタイプ

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

安定版リリース

本番環境での使用を想定した通常の安定版リリースです。

プレビューリリース

毎週火曜日 23:59 UTC にリリースされるプレビューリリースで、今後の機能を早期に利用できます。

ナイトリーリリース

最先端の開発テスト用に、毎日世界協定時刻 (UTC) の深夜0時にデイリーナイトリーリリースを実施しています。

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

ナイトリー: 毎日世界協定時刻 (UTC) 午前0時
プレビュー: 毎週火曜日世界協定時刻 (UTC) 23:59
安定版: メンテナーによる手動リリース

異なるリリースタイプの使い方

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


 
# 安定版 (デフォルト)
npm install -g @qwen-code/qwen-code
 
# プレビュー版
npm install -g @qwen-code/qwen-code@preview
 
# ナイトリー版
npm install -g @qwen-code/qwen-code@nightly

リリースプロセスの詳細

すべてのスケジュールされたリリースまたは手動リリースは、以下の手順に従います。

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

失敗時の処理

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

リリース検証

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

npx -y @qwen-code/qwen-code@latest --version を実行して、rc や dev タグを使用していない場合にプッシュが期待通りに動作したことを検証します
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 ブランチの package.json は最新の安定リリースバージョンを反映するべきであり、RC バージョンではありません。
プロセス：release-v1.3.0-rc.1 ブランチが作成され、npm publish —tag rc が実行された後、そのブランチの役目は終わります。単純に削除して構いません。RC のコードは既に main (または機能ブランチ) に存在しているため、機能的なコードは失われません。リリースブランチはバージョン番号の一時的な運搬手段に過ぎません。

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

実際にはNPMに公開したり、GitHubで公開リリースを作成せずにリリースプロセスをテストする必要がある場合は、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ディレクトリにクリーンで自己完結したパッケージを構築することです。このdistディレクトリが実際にNPMに公開されます。

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

ステージ1: リリース前チェックとバージョニング

何が起こるか: ファイルが移動される前に、プロセスはプロジェクトが正常な状態にあることを確認します。これにはテストの実行、linting、型チェック(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への公開

何が起こるか: npm publishコマンドがルートのdistディレクトリ内で実行されます。
理由: distディレクトリ内でnpm publishを実行することで、ステージ3で注意深くアセンブルしたファイルのみがNPMレジストリにアップロードされます。これにより、ソースコード、テストファイル、開発用設定が誤って公開されるのを防ぎ、ユーザーにとってクリーンで最小限のパッケージになります。

このプロセスにより、最終的に公開される成果物は、開発ワークスペースの直接コピーではなく、目的を持って構築されたクリーンで効率的なプロジェクトの表現であることが保証されます。

NPM Workspaces

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

動作原理

ルートの package.json ファイルには、このプロジェクトのワークスペースが以下のように定義されています。


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

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

ワークスペースの利点

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