Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
332 lines (207 loc) · 11.9 KB

CONTRIBUTING.md

File metadata and controls

332 lines (207 loc) · 11.9 KB
Raw

How to Contribute

We would love to accept your patches and contributions to this project.

Contribution Process

Code Reviews

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose.

Pull Request Guidelines

To help us review and merge your PRs quickly, please follow these guidelines. PRs that do not meet these standards may be closed.

1. Link to an Existing Issue

All PRs should be linked to an existing issue in our tracker. This ensures that every change has been discussed and is aligned with the project's goals before any code is written.

  • For bug fixes: The PR should be linked to the bug report issue.
  • For features: The PR should be linked to the feature request or proposal issue that has been approved by a maintainer.

If an issue for your change doesn't exist, please open one first and wait for feedback before you start coding.

2. Keep It Small and Focused

We favor small, atomic PRs that address a single issue or add a single, self-contained feature.

  • Do: Create a PR that fixes one specific bug or adds one specific feature.
  • Don't: Bundle multiple unrelated changes (e.g., a bug fix, a new feature, and a refactor) into a single PR.

As a rule of thumb, start splitting a PR once it exceeds about 1,200 changed lines. PRs above about 2,000 changed lines should either be split into a series of smaller, logical PRs that can be reviewed and merged independently, or explain in the PR description why the change needs to land together.

3. Use Draft PRs for Work in Progress

If you'd like to get early feedback on your work, please use GitHub's Draft Pull Request feature. This signals to the maintainers that the PR is not yet ready for a formal review but is open for discussion and initial feedback.

4. Ensure All Checks Pass

Before submitting your PR, ensure that all automated checks are passing by running npm run preflight. This command runs all tests, linting, and other style checks.

5. Update Documentation

If your PR introduces a user-facing change (e.g., a new command, a modified flag, or a change in behavior), you must also update the relevant documentation in the /docs directory.

6. Include a Screenshot or Video Demo

To help reviewers understand your change quickly and prioritize reviews, please attach a screenshot or short video to your PR showing the change in action.

  • For bug fixes: Show the before and after behavior.
  • For new features: Show the feature working end-to-end.
  • For refactors or internal-only changes: Simply note "N/A — no user-facing change" in the demo section.

PRs with visual demos tend to get reviewed much faster, so this is in your interest too!

7. Write Clear Commit Messages and a Good PR Description

Your PR should have a clear, descriptive title and a detailed description of the changes. Follow the Conventional Commits standard for your commit messages.

  • Good PR Title: feat(cli): Add --json flag to 'config get' command
  • Bad PR Title: Made some changes

In the PR description, explain the "why" behind your changes and link to the relevant issue (e.g., Fixes #123).

Adding a Provider Preset

A built-in preset is an endorsement, not just a convenience. Users route API keys and full prompt data through these endpoints, so the bar is high.

Tier 1 — Built-in Preset requires all of the following:

  • Affiliation Disclosure — PR author must disclose any relationship with the provider.
  • Operational Maturity — publicly operational with demonstrated uptime; public SLA or status page preferred.
  • Organic User Demand — evidence of community demand (issues, discussions), not just a self-listing.
  • Data and Security Transparency — provider's data handling practices must be publicly documented.
  • Maintenance Commitment — provider team commits to tracking Qwen Code protocol changes.

Default Path — Custom Provider: for providers that don't meet Tier 1, users connect via the built-in custom-provider flow (/auth or /model → Custom Provider). No code change or project endorsement needed.

If a Tier 1 preset is approved, the PR should follow the existing openrouter.ts / requesty.ts pattern: use customHeaders for attribution, implement ownsModel with a dual-gate (env key + hostname), and add the env key to SECRET_ENV_VARS in packages/cli/src/serve/envSnapshot.ts with corresponding test assertions in auth.test.ts and provider-config.test.ts.

Development Setup and Workflow

This section guides contributors on how to build, modify, and understand the development setup of this project.

Setting Up the Development Environment

Prerequisites:

  1. Node.js:
    • Development: Please use Node.js >=22. Ink 7 (used by the TUI) requires Node 22, and react@^19.2.0 is the matching peer. You can use a tool like nvm to manage Node.js versions.
    • Production: For running the CLI in a production environment, any version of Node.js >=22 is acceptable.
  2. Git

Build Process

To clone the repository:

git clone https://github.com/QwenLM/qwen-code.git # Or your fork's URL
cd qwen-code

To install dependencies defined in package.json as well as root dependencies, use the pnpm version the repository pins in packageManager (Corepack, bundled with Node.js, fetches it):

corepack pnpm install --frozen-lockfile

To build the entire project (all packages):

npm run build

This command typically compiles TypeScript to JavaScript, bundles assets, and prepares the packages for execution. Refer to scripts/build.js and package.json scripts for more details on what happens during the build.

Enabling Sandboxing

Sandboxing is highly recommended and requires, at a minimum, setting QWEN_SANDBOX=true in your ~/.env and ensuring a sandboxing provider (e.g. macOS Seatbelt, docker, or podman) is available. See Sandboxing for details.

To build both the qwen-code CLI utility and the sandbox container, run build:all from the root directory:

npm run build:all

To skip building the sandbox container, you can use npm run build instead.

Running

To start the Qwen Code application from the source code (after building), run the following command from the root directory:

npm start

If you'd like to run the source build outside of the qwen-code folder, you can utilize npm link path/to/qwen-code/packages/cli (see: docs) to run with qwen-code

Running Tests

This project contains two types of tests: unit tests and integration tests.

Unit Tests

To execute the unit test suite for the project:

npm run test

This will run tests located in the packages/core and packages/cli directories. Ensure tests pass before submitting any changes. For a more comprehensive check, it is recommended to run npm run preflight.

Integration Tests

The integration tests are designed to validate the end-to-end functionality of Qwen Code. They are not run as part of the default npm run test command.

To run the integration tests, use the following command:

npm run test:e2e

For more detailed information on the integration testing framework, please see the Integration Tests documentation.

Linting and Preflight Checks

To ensure code quality and formatting consistency, run the preflight check:

npm run preflight

This command will run ESLint, Prettier, all tests, and other checks as defined in the project's package.json.

ProTip

after cloning create a git precommit hook file to ensure your commits are always clean.

echo "
# Run npm build and check for errors
if ! npm run preflight; then
  echo "npm build failed. Commit aborted."
  exit 1
fi
" > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

Formatting

To separately format the code in this project by running the following command from the root directory:

npm run format

This command uses Prettier to format the code according to the project's style guidelines.

Linting

To separately lint the code in this project, run the following command from the root directory:

npm run lint

Coding Conventions

  • Please adhere to the coding style, patterns, and conventions used throughout the existing codebase.
  • Imports: Pay special attention to import paths. The project uses ESLint to enforce restrictions on relative imports between packages.

Project Structure

  • packages/: Contains the individual sub-packages of the project.
    • cli/: The command-line interface.
    • core/: The core backend logic for Qwen Code.
  • docs/: Contains all project documentation.
  • scripts/: Utility scripts for building, testing, and development tasks.

For more detailed architecture, see docs/architecture.md.

Documentation Development

This section describes how to develop and preview the documentation locally.

Prerequisites

  1. Ensure you have Node.js (version 22+) installed
  2. Have npm or yarn available

Setup Documentation Site Locally

To work on the documentation and preview changes locally:

  1. Navigate to the docs-site directory:

    cd docs-site

  2. Install dependencies:

    npm install

  3. Link the documentation content from the main docs directory:

    npm run link

    This creates a symbolic link from ../docs to content in the docs-site project, allowing the documentation content to be served by the Next.js site.

  4. Start the development server:

    npm run dev

  5. Open http://localhost:3000 in your browser to see the documentation site with live updates as you make changes.

Any changes made to the documentation files in the main docs directory will be reflected immediately in the documentation site.

Debugging

VS Code:

  1. Run the CLI to interactively debug in VS Code with F5
  2. Start the CLI in debug mode from the root directory: 
    npm run debug
    This command runs node --inspect-brk dist/index.js within the packages/cli directory, pausing execution until a debugger attaches. You can then open chrome://inspect in your Chrome browser to connect to the debugger.
  3. In VS Code, use the "Attach" launch configuration (found in .vscode/launch.json).

Alternatively, you can use the "Launch Program" configuration in VS Code if you prefer to launch the currently open file directly, but 'F5' is generally recommended.

To hit a breakpoint inside the sandbox container run:

DEBUG=1 qwen-code

Note: If you have DEBUG=true in a project's .env file, it won't affect qwen-code due to automatic exclusion. Use .qwen-code/.env files for qwen-code specific debug settings.

React DevTools

To debug the CLI's React-based UI, you can use React DevTools. Ink, the library used for the CLI's interface, is compatible with React DevTools version 4.x.

  1. Start the Qwen Code application in development mode:

    DEV=true npm start

  2. Install and run React DevTools version 4.28.5 (or the latest compatible 4.x version):

    You can either install it globally:

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

    Or run it directly using npx:

    npx react-devtools@4.28.5

    Your running CLI application should then connect to React DevTools.

Sandboxing

TBD

Manual Publish

We publish an artifact for each commit to our internal registry. But if you need to manually cut a local build, then run the following commands:

npm run clean
corepack pnpm install --frozen-lockfile
npm run auth
npm run prerelease:dev
npm publish --workspaces