Skip to Content
Руководство разработчикаРуководство по внесению вклада

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

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

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

Код-ревью

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

Руководство по запросам на вытягивание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

6. Пишите понятные сообщения коммитов и хорошее описание PR

Ваш PR должен иметь четкое, описательное название и подробное описание изменений. Следуйте стандарту Conventional Commits  для сообщений коммитов.

  • Хорошее название PR: feat(cli): Add --json flag to 'config get' command
  • Плохое название PR: Made some changes

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

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

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

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

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

  1. Node.js:
    • Разработка: Пожалуйста, используйте Node.js ~20.19.0. Эта конкретная версия требуется из-за проблемы с зависимостью на стороне разработки. Вы можете использовать инструмент типа nvm  для управления версиями Node.js.
    • Производство: Для запуска CLI в производственной среде подойдет любая версия Node.js >=20.
  2. 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 precommit hook, чтобы ваши коммиты всегда были чистыми.

echo "
 
# Запуск npm build и проверка на ошибки
if ! npm run preflight; then
  echo "npm build failed. Commit aborted."
  exit 1
fi
" > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

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

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

npm run format

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

Линтинг

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

npm run lint

Соглашения о кодировании

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

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

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

Более подробную архитектуру см. в docs/architecture.md.

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

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

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

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

Настройка локального запуска сайта документации

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

  1. Перейдите в каталог docs-site:

    cd docs-site

  2. Установите зависимости:

    npm install

  3. Свяжите содержимое документации из основного каталога docs:

    npm run link

    Эта команда создает символическую ссылку из ../docs в content проекта docs-site, что позволяет содержимому документации обслуживаться сайтом Next.js.

  4. Запустите сервер разработки:

    npm run dev

  5. Откройте http://localhost:3000  в браузере, чтобы увидеть сайт документации с живыми обновлениями при внесении изменений.

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

Отладка

VS Code:

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

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

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

DEBUG=1 qwen-code

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

React DevTools

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

  1. Запустите приложение Qwen Code в режиме разработки:

    DEV=true npm start

  2. Установите и запустите 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.

Песочница

TBD

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

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

npm run clean
npm install
npm run auth
npm run prerelease:dev
npm publish --workspaces
Last updated on
Дорожная картаTypescript SDK