> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/QwenLM/qwen-code/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing Guidelines

> How to contribute to Qwen Code development

# Contributing Guidelines

We welcome contributions to Qwen Code! This guide will help you get started with contributing to the project.

## Contribution Process

### Code Reviews

All submissions, including those from project members, require review. We use [GitHub pull requests](https://docs.github.com/articles/about-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.

Large changes should be broken down into a series of smaller, logical PRs that can be reviewed and merged independently.

#### 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:

```bash theme={null}
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. 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](https://www.conventionalcommits.org/) standard for your commit messages.

**Good PR Title Examples:**

* `feat(cli): Add --json flag to 'config get' command`
* `fix(tools): Handle ENOENT error in read-file tool`
* `docs: Update architecture documentation`

**Bad PR Title Examples:**

* `Made some changes`
* `Fix bug`
* `Update`

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

## Development Workflow

### Setting Up Your Environment

See the [Development Setup](./development-setup.mdx) guide for detailed instructions on setting up your development environment.

### Running Tests

Before submitting a PR, make sure all tests pass:

```bash theme={null}
# Run all unit tests
npm run test

# Run integration tests
npm run test:e2e

# Run all checks (recommended before committing)
npm run preflight
```

### Linting and Formatting

We use ESLint and Prettier to maintain code quality:

```bash theme={null}
# Run linter
npm run lint

# Fix linting issues automatically
npm run lint:fix

# Format code with Prettier
npm run format
```

### Coding Conventions

Please adhere to these conventions throughout the codebase:

#### TypeScript Style

* **Strict Mode:** All TypeScript strict flags are enabled
* **Type Safety:** Avoid `any` types; use proper type definitions
* **Module System:** ES modules with `.js` extensions in imports
* **Naming:**
  * `camelCase` for variables and functions
  * `PascalCase` for classes and types
  * `UPPER_SNAKE_CASE` for constants

#### Import Conventions

```typescript theme={null}
// Within a package - use relative paths with .js extension
import { something } from './utils/something.js';
import { helper } from '../helpers/helper.js';

// Between packages - use package names (enforced by ESLint)
import { Config } from '@qwen-code/qwen-code-core';
import { Command } from '@qwen-code/qwen-code-cli';

// Never use relative imports between packages
// ❌ BAD: import { Config } from '../../core/src/config/config.js';
// ✅ GOOD: import { Config } from '@qwen-code/qwen-code-core';
```

#### Testing Patterns

* **Unit Tests:** Co-located with source files using `.test.ts` suffix
* **Test Framework:** Vitest with globals enabled
* **Mocking:**
  * HTTP requests: `msw`
  * File system: `memfs` or `mock-fs`
  * Dependencies: Vitest's built-in mocking

**Example Test Structure:**

```typescript theme={null}
import { describe, it, expect, beforeEach } from 'vitest';
import { MyClass } from './my-class.js';

describe('MyClass', () => {
  let instance: MyClass;

  beforeEach(() => {
    instance = new MyClass();
  });

  it('should do something', () => {
    const result = instance.doSomething();
    expect(result).toBe('expected');
  });
});
```

#### Documentation

* **Code Comments:** Use JSDoc for public APIs
* **README Files:** Update when adding new features
* **User Documentation:** Update in `/docs` for user-facing changes
* **Architecture Docs:** Update for significant structural changes

### Pre-commit Hook

You can set up a pre-commit hook to run checks automatically:

```bash theme={null}
echo '
# Run npm preflight and check for errors
if ! npm run preflight; then
  echo "npm preflight failed. Commit aborted."
  exit 1
fi
' > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
```

## Project Structure

Understanding the project structure will help you know where to make changes:

```
qwen-code/
├── packages/
│   ├── cli/              # Command-line interface
│   ├── core/             # Core backend logic
│   ├── sdk-typescript/   # TypeScript SDK
│   ├── sdk-java/         # Java SDK
│   ├── test-utils/       # Shared testing utilities
│   ├── vscode-ide-companion/  # VS Code extension
│   ├── webui/            # Web UI components
│   └── zed-extension/    # Zed editor extension
├── docs/                 # Documentation source
├── docs-site/            # Documentation website
├── integration-tests/    # End-to-end tests
├── scripts/              # Build and utility scripts
└── eslint-rules/         # Custom ESLint rules
```

## Common Contribution Scenarios

### Adding a New Tool

1. Create a new file in `packages/core/src/tools/`
2. Extend `BaseDeclarativeTool`
3. Implement required methods
4. Add tests in a `.test.ts` file
5. Register the tool in the tool registry
6. Update documentation

See [Tools System](./tools-system.mdx) for detailed instructions.

### Adding a New Command

1. Create a command handler in `packages/cli/src/commands/`
2. Register the command in the command registry
3. Add tests
4. Update help text and documentation

### Fixing a Bug

1. Add a test that reproduces the bug
2. Fix the bug
3. Ensure the test passes
4. Add any additional tests for edge cases
5. Update documentation if behavior changed

### Improving Documentation

1. Documentation files are in `/docs`
2. Use MDX format for documentation pages
3. Test locally using the docs-site (see below)
4. Follow the existing documentation structure

## Documentation Development

### Prerequisites

* Node.js 18+
* npm or yarn

### Local Documentation Preview

```bash theme={null}
# Navigate to docs-site directory
cd docs-site

# Install dependencies
npm install

# Link documentation content
npm run link

# Start dev server
npm run dev

# Open http://localhost:3000
```

Any changes to files in the `/docs` directory will be reflected immediately in the documentation site.

## Debugging

### VS Code Debugging

1. Press `F5` to launch with debugger attached
2. Or run: `npm run debug`
3. Use breakpoints in VS Code

### React DevTools (for CLI UI)

```bash theme={null}
# Start in development mode
DEV=true npm start

# In another terminal, launch React DevTools
npx react-devtools@4.28.5
```

### Sandbox Debugging

```bash theme={null}
# Enable debug mode for sandbox
DEBUG=1 qwen-code
```

## Getting Help

If you need help or have questions:

1. Check the [documentation](https://qwenlm.github.io/qwen-code-docs/)
2. Search [existing issues](https://github.com/QwenLM/qwen-code/issues)
3. Ask in [discussions](https://github.com/QwenLM/qwen-code/discussions)
4. Open a new issue if needed

## Code of Conduct

Please be respectful and constructive in all interactions. We're all here to build something great together.

## License

By contributing to Qwen Code, you agree that your contributions will be licensed under the Apache 2.0 License.