diff --git a/docs/developers/development/npm.md b/docs/developers/development/npm.md index f6dd1145..76dfb72d 100644 --- a/docs/developers/development/npm.md +++ b/docs/developers/development/npm.md @@ -31,42 +31,57 @@ Releases are managed through the [release.yml](https://github.com/QwenLM/qwen-co - **Dry Run**: Leave as `true` to test the workflow without publishing, or set to `false` to perform a live release. 5. Click **Run workflow**. -## Nightly Releases +## Release Types -In addition to manual releases, this project has an automated nightly release process to provide the latest "bleeding edge" version for testing and development. +The project supports multiple types of releases: -### Process +### Stable Releases -Every night at midnight UTC, the [Release workflow](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) runs automatically on a schedule. It performs the following steps: +Regular stable releases for production use. -1. Checks out the latest code from the `main` branch. -2. Installs all dependencies. -3. Runs the full suite of `preflight` checks and integration tests. -4. If all tests succeed, it calculates the next nightly version number (e.g., `v0.2.1-nightly.20230101`). -5. It then builds and publishes the packages to npm with the `nightly` dist-tag. -6. Finally, it creates a GitHub Release for the nightly version. +### Preview Releases -### Failure Handling +Weekly preview releases every Tuesday at 23:59 UTC for early access to upcoming features. -If any step in the nightly workflow fails, it will automatically create a new issue in the repository with the labels `bug` and `nightly-failure`. The issue will contain a link to the failed workflow run for easy debugging. +### Nightly Releases -### How to Use the Nightly Build +Daily nightly releases at midnight UTC for bleeding-edge development testing. -To install the latest nightly build, use the `@nightly` tag: +## Automated Release Schedule + +- **Nightly**: Every day at midnight UTC +- **Preview**: Every Tuesday at 23:59 UTC +- **Stable**: Manual releases triggered by maintainers + +### How to Use Different Release Types + +To install the latest version of each type: ```bash +# 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 ``` -We also run a Google cloud build called [release-docker.yml](../.gcp/release-docker.yml). Which publishes the sandbox docker to match your release. This will also be moved to GH and combined with the main release file once service account permissions are sorted out. +### Release Process Details -### After the Release +Every scheduled or manual release follows these steps: -After the workflow has successfully completed, you can monitor its progress in the [GitHub Actions tab](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml). Once complete, you should: +1. Checks out the specified code (latest from `main` branch or specific commit). +2. Installs all dependencies. +3. Runs the full suite of `preflight` checks and integration tests. +4. If all tests succeed, it calculates the appropriate version number based on release type. +5. Builds and publishes the packages to npm with the appropriate dist-tag. +6. Creates a GitHub Release for the version. -1. Go to the [pull requests page](https://github.com/QwenLM/qwen-code/pulls) of the repository. -2. Create a new pull request from the `release/vX.Y.Z` branch to `main`. -3. Review the pull request (it should only contain version updates in `package.json` files) and merge it. This keeps the version in `main` up-to-date. +### Failure Handling + +If any step in the release workflow fails, it will automatically create a new issue in the repository with the labels `bug` and a type-specific failure label (e.g., `nightly-failure`, `preview-failure`). The issue will contain a link to the failed workflow run for easy debugging. ## Release Validation @@ -155,7 +170,7 @@ By performing a dry run, you can be confident that your changes to the packaging ## Release Deep Dive The main goal of the release process is to take the source code from the packages/ directory, build it, and assemble a -clean, self-contained package in a temporary `bundle` directory at the root of the project. This `bundle` directory is what +clean, self-contained package in a temporary `dist` directory at the root of the project. This `dist` directory is what actually gets published to NPM. Here are the key stages: @@ -177,83 +192,46 @@ Stage 2: Building the Source Code - Why: The TypeScript code written during development needs to be converted into plain JavaScript that can be run by Node.js. The core package is built first as the cli package depends on it. -Stage 3: Assembling the Final Publishable Package +Stage 3: Bundling and Assembling the Final Publishable Package -This is the most critical stage where files are moved and transformed into their final state for publishing. A temporary -`bundle` folder is created at the project root to house the final package contents. +This is the most critical stage where files are moved and transformed into their final state for publishing. The process uses modern bundling techniques to create the final package. -1. The `package.json` is Transformed: - - What happens: The package.json from packages/cli/ is read, modified, and written into the root `bundle`/ directory. - - File movement: packages/cli/package.json -> (in-memory transformation) -> `bundle`/package.json - - Why: The final package.json must be different from the one used in development. Key changes include: - - Removing devDependencies. - - Removing workspace-specific "dependencies": { "@qwen-code/core": "workspace:\*" } and ensuring the core code is - bundled directly into the final JavaScript file. - - Ensuring the bin, main, and files fields point to the correct locations within the final package structure. +1. Bundle Creation: + - What happens: The prepare-package.js script creates a clean distribution package in the `dist` directory. + - Key transformations: + - Copies README.md and LICENSE to dist/ + - Copies locales folder for internationalization + - Creates a clean package.json for distribution with only necessary dependencies + - Includes runtime dependencies like tiktoken + - Maintains optional dependencies for node-pty 2. The JavaScript Bundle is Created: - What happens: The built JavaScript from both packages/core/dist and packages/cli/dist are bundled into a single, - executable JavaScript file. - - File movement: packages/cli/dist/index.js + packages/core/dist/index.js -> (bundled by esbuild) -> `bundle`/gemini.js (or a - similar name). + executable JavaScript file using esbuild. + - File location: dist/cli.js - Why: This creates a single, optimized file that contains all the necessary application code. It simplifies the package - by removing the need for the core package to be a separate dependency on NPM, as its code is now included directly. + by removing the need for complex dependency resolution at install time. 3. Static and Supporting Files are Copied: - What happens: Essential files that are not part of the source code but are required for the package to work correctly - or be well-described are copied into the `bundle` directory. + or be well-described are copied into the `dist` directory. - File movement: - - README.md -> `bundle`/README.md - - LICENSE -> `bundle`/LICENSE - - packages/cli/src/utils/\*.sb (sandbox profiles) -> `bundle`/ + - README.md -> dist/README.md + - LICENSE -> dist/LICENSE + - locales/ -> dist/locales/ + - Vendor files -> dist/vendor/ - Why: - The README.md and LICENSE are standard files that should be included in any NPM package. - - The sandbox profiles (.sb files) are critical runtime assets required for the CLI's sandboxing feature to - function. They must be located next to the final executable. + - Locales support internationalization features + - Vendor files contain necessary runtime dependencies Stage 4: Publishing to NPM -- What happens: The npm publish command is run from inside the root `bundle` directory. -- Why: By running npm publish from within the `bundle` directory, only the files we carefully assembled in Stage 3 are uploaded +- What happens: The npm publish command is run from inside the root `dist` directory. +- Why: By running npm publish from within the `dist` directory, only the files we carefully assembled in Stage 3 are uploaded to the NPM registry. This prevents any source code, test files, or development configurations from being accidentally published, resulting in a clean and minimal package for users. -Summary of File Flow - -```bash -graph TD - subgraph "Source Files" - A["packages/core/src/*.ts
packages/cli/src/*.ts"] - B["packages/cli/package.json"] - C["README.md
LICENSE
packages/cli/src/utils/*.sb"] - end - - subgraph "Process" - D(Build) - E(Transform) - F(Assemble) - G(Publish) - end - - subgraph "Artifacts" - H["Bundled JS"] - I["Final package.json"] - J["bundle/"] - end - - subgraph "Destination" - K["NPM Registry"] - end - - A --> D --> H - B --> E --> I - C --> F - H --> F - I --> F - F --> J - J --> G --> K -``` - This process ensures that the final published artifact is a purpose-built, clean, and efficient representation of the project, rather than a direct copy of the development workspace. diff --git a/docs/developers/development/telemetry.md b/docs/developers/development/telemetry.md index a91ffb3e..f5faee40 100644 --- a/docs/developers/development/telemetry.md +++ b/docs/developers/development/telemetry.md @@ -47,6 +47,10 @@ observability framework — Qwen Code's observability system provides: ## Configuration +> [!note] +> +> **⚠️ Special Note: This feature requires corresponding code changes. This documentation is provided in advance; please refer to future code updates for actual functionality.** + All telemetry behavior is controlled through your `.qwen/settings.json` file. These settings can be overridden by environment variables or CLI flags. diff --git a/docs/users/features/_meta.ts b/docs/users/features/_meta.ts index f766c41a..c55943ce 100644 --- a/docs/users/features/_meta.ts +++ b/docs/users/features/_meta.ts @@ -1,9 +1,10 @@ export default { + commands: 'Commands', 'sub-agents': 'SubAgents', + headless: 'Headless Mode', checkpointing: { display: 'hidden', }, - headless: 'Headless Mode', 'approval-mode': 'Approval Mode', 'token-caching': 'Token Caching', mcp: 'MCP', diff --git a/docs/users/reference/cli-reference.md b/docs/users/features/commands.md similarity index 97% rename from docs/users/reference/cli-reference.md rename to docs/users/features/commands.md index a8557bdf..92833b4e 100644 --- a/docs/users/reference/cli-reference.md +++ b/docs/users/features/commands.md @@ -1,4 +1,4 @@ -# Qwen Code Command Reference +# Commands This document details all commands supported by Qwen Code, helping you efficiently manage sessions, customize the interface, and control its behavior. @@ -183,10 +183,10 @@ Naming Rules: Path separator (`/` or `\`) converted to colon (`:`) | Operation | User Interaction | | ------------------------------- | -------------------- | | 1. Parse command and parameters | - | -| 2. Automatic Shell escaping | - | -| 3. Show confirmation dialog | ✅ User confirmation | -| 4. Execute command | - | -| 5. Inject output to prompt | - | +| 2. Automatic Shell escaping | - | +| 3. Show confirmation dialog | ✅ User confirmation | +| 4. Execute command | - | +| 5. Inject output to prompt | - | Example: Git Commit Message Generation @@ -228,9 +228,9 @@ Review {{args}}, reference standards: | Operation | Command/Code | | ----------------------------- | ------------------------------------------- | | 1. Create directory structure | `mkdir -p ~/.qwen/commands/refactor` | -| 2. Create command file | `touch ~/.qwen/commands/refactor/pure.toml` | -| 3. Edit command content | Refer to the complete code below. | -| 4. Test command | `@file.js` → `/refactor:pure` | +| 2. Create command file | `touch ~/.qwen/commands/refactor/pure.toml` | +| 3. Edit command content | Refer to the complete code below. | +| 4. Test command | `@file.js` → `/refactor:pure` | ```# ~/.qwen/commands/refactor/pure.toml description = "Refactor code to pure function"