alibaba__open-code-review/CONTRIBUTING.ru-RU.md

Участие в разработке OpenCodeReview

Спасибо за интерес к развитию OpenCodeReview! Важен любой вклад — будь то исправленная опечатка, сообщение о баге или новая функциональность.

English | 简体中文版 | 日本語版 | 한국어 | Русский

Кодекс поведения

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

Как можно помочь

Помимо написания кода, есть много способов внести вклад:

• Сообщайте о багах — нашли поломку? Заведите issue с шагами воспроизведения.
• Предлагайте улучшения — есть идея? Начните обсуждение в GitHub Discussions или заведите issue Feature Request.
• Улучшайте документацию — исправляйте опечатки, проясняйте формулировки, добавляйте примеры. Чтобы сообщить о проблеме, можно также завести Documentation Issue.
• Ревьюйте pull request'ы — помогайте нам проверять код других контрибьюторов.
• Пишите код — исправляйте баги, добавляйте функциональность, улучшайте производительность.

С чего начать

Требования

• Go 1.25+
• Git
• Make

Настройка

# 1. Сделайте форк репозитория на GitHub

# 2. Склонируйте свой форк
git clone https://github.com/<your-username>/open-code-review.git
cd open-code-review

# 3. Добавьте remote upstream (для синхронизации с основным репозиторием)
git remote add upstream https://github.com/alibaba/open-code-review.git

# 4. Соберите проект
make build

# 5. Запустите тесты
make test

Если всё прошло успешно — вы готовы контрибьютить.

Примечание: remote upstream для контрибьюторов доступен только на чтение — он используется, чтобы подтягивать свежие изменения из основного репозитория. Пушить напрямую в upstream нельзя. Все изменения отправляются в ваш форк (origin) и подаются через Pull Request.

Процесс разработки

Ветки

Создайте feature-ветку от main:

git checkout main
git pull upstream main
git checkout -b feat/your-feature-name

Используйте префиксы, обозначающие тип изменения:

Префикс	Назначение
feat/	Новая функциональность
fix/	Исправление бага
docs/	Только документация
refactor/	Рефакторинг (без изменения поведения)
test/	Добавление или обновление тестов
chore/	Сборка, CI или инструментарий

Сообщения коммитов

Следуйте формату Conventional Commits:

<type>(<scope>): <краткое описание>

[необязательное тело]

Примеры:

feat(agent): add support for custom tool definitions
fix(llm): handle timeout errors in Anthropic API calls
docs(README): update configuration examples

Заголовки лицензии

Каждый исходный файл (.go, .sh, .js, .mjs, .ts, .tsx) должен содержать заголовок лицензии SPDX. После создания новых файлов выполните:

make license-add

Эта команда автоматически добавит необходимый заголовок. CI отклонит PR с отсутствующими заголовками.

Качество кода

Перед отправкой изменений убедитесь, что они проходят все проверки:

# Форматирование, линт и проверка заголовков лицензии
make check

# Тесты с детектором гонок
make test

# Успешная сборка
make build

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

├── cmd/opencodereview/   # Точка входа CLI
├── internal/
│   ├── agent/            # Логика ревью-агента
│   ├── config/           # Управление конфигурацией
│   ├── diff/             # Разбор git-диффов
│   ├── llm/              # Клиент LLM API (Anthropic и OpenAI)
│   ├── model/            # Модели данных
│   ├── session/          # Управление сессиями ревью
│   ├── tool/             # Встроенные инструменты (file_read, code_search и др.)
│   ├── telemetry/        # Интеграция с OpenTelemetry
│   └── viewer/           # WebUI-просмотрщик сессий
├── pages/                # Фронтенд WebUI
├── scripts/              # Скрипты сборки и установки
└── bin/                  # NPM-обёртка

Разработка с помощью ИИ

Пользоваться помощью ИИ при разработке — это совершенно нормально, и мы только рады, если так вам проще вносить вклад. Чего мы принять не можем — это когда сгенерированный моделью код попадает в коммит непрочитанным, а его избыточность и ошибки никто не исправляет. Такие изменения замедляют обсуждение на ревью и мешают продвигать pull request.

Если ИИ участвовал в вашей работе, соблюдайте приведённые ниже правила.

Правила:

1. Вы должны раскрыть в начальном issue или pull request, что использовали ИИ/LLM, а также указать использованные инструменты/модели и т.п.
2. Вы должны понимать каждую строку кода, написанную ИИ, и знать, что именно сделал ИИ.
3. Когда ревьюер спрашивает о причине какого-либо изменения, вы должны уметь объяснить её сами, независимо от того, написали его вы или ИИ. Содержание ваших ответов на вопросы мейнтейнеров и замечания по ревью должно исходить из вашего собственного понимания — ИИ/LLM можно использовать только для перевода или редактирования формулировок, но не для генерации самого ответа.
4. В вашем PR не должно быть повторяющихся циклов вида ИИ сгенерировал -> исправил -> исправил -> исправил. Это может указывать на то, что вы не проверяли код, сгенерированный ИИ, а позволяли ИИ исправлять проблемы по мере их возникновения — снова и снова.
5. Прежде чем активно просить кого-либо из участников провести ревью, вы должны сначала сами проверить весь код, текст и другие материалы, созданные ИИ/LLM.
6. Вы не должны приписывать коммиты ИИ/LLM, в том числе через трейлеры «Assisted-by», «Co-developed-by» или аналогичные.
7. Не пишите слишком длинные сообщения коммитов. Важную информацию следует указывать в описании PR, а не в свёрнутых сообщениях коммитов.
8. Если вы не хотите или не можете выполнить всё вышеперечисленное, пожалуйста, закройте свой issue или pull request.

Спасибо!

Вклад в документацию

Документация — важнейшая часть OpenCodeReview. Мы приветствуем улучшения README-файлов, комментариев в коде, примеров конфигурации и любых текстов, обращённых к пользователю.

Что считается вкладом в документацию

• Исправление опечаток, грамматических ошибок и битых ссылок
• Прояснение запутанных объяснений и добавление недостающего контекста
• Добавление примеров использования команд и параметров конфигурации
• Обновление устаревшего содержимого (например, после изменения функциональности)
• Перевод и улучшение локализованной документации (README.zh-CN.md, README.ja-JP.md, README.ko-KR.md, README.ru-RU.md, CONTRIBUTING.zh-CN.md, CONTRIBUTING.ja-JP.md, CONTRIBUTING.ko-KR.md, CONTRIBUTING.ru-RU.md)

Процесс работы с документацией

1. Если вы заметили проблему, но не планируете исправлять её сами, заведите Documentation Issue.
2. Если хотите исправить сами — сделайте форк, внесите изменения и подайте PR с префиксом ветки docs/ (например, docs/fix-config-example).
3. PR, затрагивающие только документацию, не требуют изменений в тестах, но, пожалуйста, проверяйте точность всех приводимых команд и фрагментов кода.

Файлы документации

Файл	Назначение
README.md	Основная документация проекта (английский)
README.zh-CN.md	Китайский перевод
README.ja-JP.md	Японский перевод
README.ko-KR.md	Корейский перевод
README.ru-RU.md	Русский перевод
CONTRIBUTING.md	Руководство контрибьютора (английский)
CONTRIBUTING.zh-CN.md	Руководство контрибьютора (китайский)
CONTRIBUTING.ja-JP.md	Руководство контрибьютора (японский)
CONTRIBUTING.ko-KR.md	Руководство контрибьютора (корейский)
CONTRIBUTING.ru-RU.md	Руководство контрибьютора (русский)

Отправка изменений

Заведение issue

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

Сообщая о баге, укажите:

1. Версию OpenCodeReview (ocr version)
2. ОС и архитектуру
3. Шаги воспроизведения
4. Ожидаемое и фактическое поведение
5. Релевантные логи или сообщения об ошибках

Процесс Pull Request

1. Держите PR сфокусированным — одно логическое изменение на PR. Несколько независимых изменений лучше подать отдельными PR.
2. Пишите тесты — добавляйте или обновляйте тесты при любых изменениях поведения.
3. Обновляйте документацию — если изменение затрагивает видимое пользователю поведение, обновите соответствующую документацию.
4. Подпишите CLA — прежде чем PR может быть принят, все контрибьюторы должны подписать Contributor License Agreement (см. ниже).
5. Заполните шаблон PR — опишите, что делает ваше изменение и зачем оно нужно.

Формат заголовка PR

Используйте тот же формат Conventional Commits, что и для сообщений коммитов:

feat(agent): add support for custom tool definitions

Процесс ревью

• Мейнтейнер посмотрит ваш PR — обычно в течение нескольких рабочих дней.
• Мы можем попросить внести изменения — это нормальная совместная работа, а не противостояние.
• После одобрения мейнтейнер смёржит ваш PR.

Как ускорить рассмотрение вашего PR

Хотите, чтобы ваш PR был рассмотрен и принят быстрее? Следующие практики помогут:

• Подпишите CLA заранее — Многие контрибьюторы-новички застревают, потому что пропускают комментарий CLA-бота. Подпишите Contributor License Agreement сразу, как только бот предложит — PR без подписанного CLA не может быть принят.
• Убедитесь, что все проверки CI пройдены — PR с непройденными проверками не будет рассматриваться. Перед отправкой запустите make test и make build локально, чтобы выявить проблемы заранее.
• Делайте изменения фокусированными и небольшими — PR, который делает одну вещь хорошо, гораздо проще ревьюить, чем тот, который смешивает несвязанные изменения. Маленькие PR ревьюятся быстрее и реже требуют нескольких раундов правок.
• Пишите чёткое и точное описание — Объясните, что изменилось и почему. Описание должно соответствовать реальному diff — если они расходятся, ревьюер теряет доверие. Если объём работы изменился в процессе разработки, обновите описание перед запросом ревью.
• Добавляйте тесты для изменений поведения — Новые функции или исправления без тестов вызывают вопросы. Тесты демонстрируют корректность и помогают ревьюерам понять ожидаемое поведение.
• Следуйте существующим паттернам кода — Придерживайтесь стиля, соглашений об именовании и архитектуры окружающего кода. Единообразие снижает когнитивную нагрузку на ревьюера и позволяет избежать замечаний, касающихся только стиля.
• Оперативно реагируйте на обратную связь — Когда ревьюер запрашивает изменения, обработайте их быстро, чтобы сократить цикл ревью. Если вы не согласны, объясните свою позицию, а не игнорируйте комментарий.

Лицензионное соглашение контрибьютора (CLA)

Прежде чем мы сможем принять ваш вклад, необходимо подписать Alibaba Open Source Contributor License Agreement. Это гарантирует, что проект может распространяться на условиях своей лицензии.

Когда вы откроете свой первый PR, CLA-бот оставит комментарий с инструкциями. Просто перейдите по ссылке и подпишите соглашение электронно — это занимает минуту.

Новичкам

Впервые в проекте? Ищите issues с метками:

• good first issue — небольшие, хорошо очерченные задачи, идеальные для старта.
• help wanted — задачи, где мы будем рады помощи сообщества.

С чего удобно начать:

• Улучшение сообщений об ошибках и вывода CLI
• Написание тестов для непокрытых участков кода
• Улучшение документации

Сообщество

• Сообщения о багах — GitHub Issues
• Предложения функциональности — GitHub Discussions (Ideas) или issue Feature Request
• Вопросы и помощь — если у вас есть вопросы об использовании OpenCodeReview, задавайте их в GitHub Discussions

Лицензия

Внося вклад в OpenCodeReview, вы соглашаетесь с тем, что ваш вклад будет лицензирован на условиях Apache License 2.0.