Skip to main content

​
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 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. 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: 
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 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 guide for detailed instructions on setting up your development environment.

​
Running Tests

Before submitting a PR, make sure all tests pass: 
# 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: 
# 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

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

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

# Start in development mode
DEV=true npm start

# In another terminal, launch React DevTools
npx [email protected]

​
Sandbox Debugging

# Enable debug mode for sandbox
DEBUG=1 qwen-code

​
Getting Help

If you need help or have questions:
  1. Check the documentation
  2. Search existing issues
  3. Ask in 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.