Как внести вклад

Мы будем рады принять ваши исправления и вклад в этот проект.

Процесс внесения вклада

Код-ревью

Все отправки, включая отправки от членов проекта, требуют проверки. Для этой цели мы используем пул-реквесты GitHub .

Руководство по пул-реквестам

Чтобы помочь нам быстро рассмотреть и объединить ваши пул-реквесты, соблюдайте следующие рекомендации. Пул-реквесты, не соответствующие этим стандартам, могут быть закрыты.

1. Ссылка на существующую задачу

Все запросы на слияние (PR) должны быть связаны с существующей задачей в нашем трекере. Это гарантирует, что каждое изменение было обсуждено и согласовано с целями проекта до написания любого кода.

Для исправлений ошибок: PR должен быть связан с задачей, описывающей ошибку.
Для новых функций: PR должен быть связан с задачей запроса или предложения новой функции, одобренной одним из сопровождающих.

Если задача для вашего изменения отсутствует, пожалуйста, сначала создайте её, дождитесь обратной связи и только после этого приступайте к написанию кода.

2. Делайте PR небольшими и сфокусированными

Мы предпочитаем небольшие, атомарные PR, направленные на решение одной конкретной задачи или добавление одной самостоятельной функции.

Делайте: Создавайте PR, который исправляет одну конкретную ошибку или добавляет одну конкретную функцию.
Не делайте: Не объединяйте несколько несвязанных изменений (например, исправление ошибки, новую функцию и рефакторинг) в один PR.

Крупные изменения следует разбить на серию небольших, логически связанных PR, которые можно независимо проверять и сливать.

3. Используйте черновые PR для работы в процессе

Если вы хотите получить раннюю обратную связь по своей работе, используйте функцию черновых pull request в GitHub. Это сигнализирует сопровождающим, что PR пока не готов к формальному ревью, но открыт для обсуждения и получения первоначальной обратной связи.

4. Убедитесь, что все проверки пройдены

Перед отправкой PR убедитесь, что все автоматизированные проверки проходят успешно, выполнив команду npm run preflight. Эта команда запускает все тесты, проверку кода на соответствие правилам линтинга и другие стилевые проверки.

5. Обновите документацию

Если ваш PR вносит изменения, видимые пользователю (например, добавляет новую команду, изменяет флаг или меняет поведение), вы также должны обновить соответствующую документацию в каталоге /docs.

6. Пишите понятные сообщения коммитов и содержательное описание запроса на слияние (PR)

Заголовок вашего PR должен быть чётким и описательным, а описание — подробно раскрывать суть вносимых изменений. Для сообщений коммитов соблюдайте стандарт Conventional Commits .

Хороший заголовок PR: feat(cli): Добавить флаг --json к команде 'config get'
Плохой заголовок PR: Внесены некоторые изменения

В описании PR объясните, почему вы вносите эти изменения, и укажите ссылку на соответствующую задачу (например, Fixes #123).

Настройка среды разработки и рабочий процесс

Этот раздел содержит руководство для участников по сборке, модификации и пониманию среды разработки данного проекта.

Настройка среды разработки

Предварительные требования:

Node.js:
- Разработка: Используйте Node.js версии ~20.19.0. Эта конкретная версия необходима из-за проблемы с зависимостью на стороне上游-разработки. Для управления версиями Node.js можно использовать инструмент вроде nvm .
- Продакшн: Для запуска CLI в продакшн-среде подойдёт любая версия Node.js >=20.
Git

Процесс сборки

Чтобы клонировать репозиторий:


git clone https://github.com/QwenLM/qwen-code.git # Или URL вашего форка
cd qwen-code

Чтобы установить зависимости, определённые в package.json, а также корневые зависимости:


npm install

Чтобы собрать весь проект (все пакеты):


npm run build

Эта команда обычно компилирует TypeScript в JavaScript, объединяет ресурсы и готовит пакеты к выполнению. Подробнее о том, что происходит во время сборки, см. в файлах scripts/build.js и скриптах в package.json.

Включение песочницы

Включение песочницы настоятельно рекомендуется и требует, как минимум, установки переменной QWEN_SANDBOX=true в файле ~/.env, а также наличия провайдера песочницы (например, macOS Seatbelt, docker или podman). Подробнее см. раздел Песочница.

Чтобы собрать как утилиту командной строки qwen-code, так и контейнер песочницы, выполните команду build:all из корневого каталога:


npm run build:all

Чтобы пропустить сборку контейнера песочницы, используйте вместо этого команду npm run build.

Запуск

Чтобы запустить приложение Qwen Code из исходного кода (после сборки), выполните следующую команду из корневого каталога:


npm start

Если вы хотите запустить собранную версию вне каталога qwen-code, вы можете использовать команду npm link path/to/qwen-code/packages/cli (см.: документацию ) для запуска с помощью команды qwen-code.

Запуск тестов

Этот проект содержит два типа тестов: модульные тесты и интеграционные тесты.

Модульные тесты

Чтобы запустить набор модульных тестов для проекта, выполните:


npm run test

Эта команда запускает тесты, расположенные в каталогах packages/core и packages/cli. Убедитесь, что все тесты проходят успешно, прежде чем отправлять какие-либо изменения. Для более полной проверки рекомендуется выполнить команду npm run preflight.

Интеграционные тесты

Интеграционные тесты предназначены для проверки сквозной функциональности Qwen Code. Они не выполняются по умолчанию при вызове команды npm run test.

Чтобы запустить интеграционные тесты, используйте следующую команду:


npm run test:e2e

Дополнительную информацию о фреймворке интеграционного тестирования см. в документации по интеграционным тестам.

Проверка кода и предварительные проверки

Чтобы обеспечить высокое качество кода и единообразие форматирования, выполните предварительную проверку:


npm run preflight

Эта команда запускает ESLint, Prettier, все тесты и другие проверки, определённые в файле package.json проекта.

Полезный совет

После клонирования репозитория создайте git-хук для предкоммита, чтобы гарантировать чистоту ваших коммитов.


echo "
 
# Запуск npm build и проверка ошибок
if ! npm run preflight; then
  echo "Сборка npm завершилась с ошибкой. Коммит отменён."
  exit 1
fi
" > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

Форматирование

Чтобы отформатировать код в этом проекте отдельно, выполните следующую команду из корневой директории:


npm run format

Эта команда использует Prettier для форматирования кода в соответствии с правилами стиля проекта.

Проверка кода (linting)

Чтобы отдельно выполнить проверку кода (linting) в этом проекте, выполните следующую команду из корневой директории:


npm run lint

Правила написания кода

Соблюдайте стиль кодирования, шаблоны и соглашения, используемые во всём существующем коде проекта.
Импорты: Особое внимание уделите путям импорта. В проекте используется ESLint для применения ограничений на относительные импорты между пакетами.

Структура проекта

packages/: содержит отдельные подпакеты проекта.
- cli/: интерфейс командной строки.
- core/: основная серверная логика Qwen Code.
docs/: содержит всю документацию проекта.
scripts/: вспомогательные скрипты для сборки, тестирования и задач разработки.

Для более подробного описания архитектуры см. docs/architecture.md.

Разработка документации

В этом разделе описано, как разрабатывать и предварительно просматривать документацию локально.

Предварительные требования

Убедитесь, что у вас установлен Node.js (версия 18 или новее).
У вас должен быть доступен npm или yarn.

Локальная настройка сайта документации

Чтобы работать с документацией и просматривать изменения локально:

Перейдите в каталог docs-site:
```
cd docs-site
```
Установите зависимости:
```
npm install
```
Свяжите содержимое документации из основного каталога docs:
```
npm run link
```
Эта команда создаёт символическую ссылку из ../docs в content внутри проекта docs-site, что позволяет сайту Next.js отдавать содержимое документации.
Запустите сервер разработки:
```
npm run dev
```
Откройте http://localhost:3000 в браузере, чтобы просмотреть сайт документации с обновлением в реальном времени по мере внесения изменений.

Любые изменения, внесённые в файлы документации в основном каталоге docs, немедленно отразятся на сайте документации.

Отладка

VS Code:

Запустите CLI для интерактивной отладки в VS Code с помощью клавиши F5.
Запустите CLI в режиме отладки из корневой директории:
```
npm run debug
```
Эта команда выполняет node --inspect-brk dist/index.js внутри директории packages/cli, приостанавливая выполнение до подключения отладчика. Затем вы можете открыть chrome://inspect в браузере Chrome, чтобы подключиться к отладчику.
В VS Code используйте конфигурацию запуска «Attach» (присоединение), указанную в файле .vscode/launch.json.

В качестве альтернативы вы можете использовать конфигурацию «Launch Program» в VS Code, если предпочитаете запускать напрямую текущий открытый файл, однако рекомендуется использовать клавишу F5.

Чтобы остановиться на точке останова внутри контейнера песочницы, выполните:


DEBUG=1 qwen-code

Примечание: Если в файле .env проекта задана переменная DEBUG=true, это не повлияет на qwen-code, поскольку она автоматически исключается. Для отладочных настроек, специфичных для qwen-code, используйте файлы .qwen-code/.env.

React DevTools

Для отладки интерфейса CLI на основе React можно использовать React DevTools. Библиотека Ink, используемая для интерфейса CLI, совместима с React DevTools версии 4.x.

Запустите приложение Qwen Code в режиме разработки:
```
DEV=true npm start
```
Установите и запустите React DevTools версии 4.28.5 (или последнюю совместимую версию 4.x):

Можно установить её глобально:
```
npm install -g react-devtools@4.28.5
react-devtools
```
Или запустить напрямую через npx:
```
npx react-devtools@4.28.5
```
Запущенное приложение CLI автоматически подключится к React DevTools.

Изолированная среда (Sandboxing)

Требуется уточнение

Ручная публикация

Мы публикуем артефакт для каждого коммита в наш внутренний реестр. Однако если вам необходимо вручную создать локальную сборку, выполните следующие команды:


npm run clean
npm install
npm run auth
npm run prerelease:dev
npm publish --workspaces