mirror of
https://github.com/alibaba/open-code-review.git
synced 2026-08-21 06:34:29 +00:00
533b526b4c
Some checks are pending
CI / cross-compile (arm64, darwin) (push) Waiting to run
CI / cross-compile (arm64, linux) (push) Waiting to run
CI / cross-compile (arm64, windows) (push) Waiting to run
CI / test (push) Waiting to run
CI / cross-compile (amd64, darwin) (push) Waiting to run
CI / cross-compile (amd64, windows) (push) Waiting to run
CodeQL Advanced / Analyze (go) (push) Waiting to run
CodeQL Advanced / Analyze (actions) (push) Waiting to run
CodeQL Advanced / Analyze (javascript-typescript) (push) Waiting to run
Deploy Pages / build (push) Waiting to run
Deploy Pages / deploy (push) Blocked by required conditions
* chore: add SPDX license headers to all source files
Add Apache-2.0 SPDX license identifiers and copyright notices to all
tracked .go, .sh, .js, .mjs, .ts, and .tsx source files.
Introduce scripts/verify-license.sh and scripts/add-license.sh for
automated verification and bulk addition of license headers. Integrate
the check into CI (ci.yml) and the Makefile (license-check target as
a prerequisite of the existing check target).
This satisfies the OpenSSF Best Practices Badge requirements for
copyright_per_file and license_per_file.
* fix: restore execute permissions on scripts
* docs: add license header instructions to CONTRIBUTING guides
* docs: add license header instructions to pages contributing guides
* fix(pages): strip unclosed HTML comment markers to satisfy CodeQL
* fix: apply code review suggestions for license scripts
- Fix portability: detect macOS vs Linux stat for permission copy
- Fix has_header: check both SPDX and copyright (match verify logic)
- Fix is_ignored: match on path boundaries to avoid false positives
- Fix year extraction: use consistent pipeline across both scripts
- Fix Bash 3.2 compat: quote array length expansion for set -u
* fix(pages): use loop-until-clean for HTML comment stripping (CodeQL)
* fix(pages): use split/join instead of replace to avoid CodeQL false positive
CodeQL's js/incomplete-multi-character-sanitization rule flags any
.replace() that removes multi-character sequences like '<!--...-->',
regardless of context. The data here comes from readFileSync on the
project's own index.html (no untrusted input), making this a false
positive. Using split(regex).join('') achieves the same result without
triggering the taint-tracking rule.
245 lines
17 KiB
Markdown
245 lines
17 KiB
Markdown
# Участие в разработке OpenCodeReview
|
||
|
||
Спасибо за интерес к развитию OpenCodeReview! Важен любой вклад — будь то исправленная опечатка, сообщение о баге или новая функциональность.
|
||
|
||
[English](CONTRIBUTING.md) | [简体中文版](CONTRIBUTING.zh-CN.md) | [日本語版](CONTRIBUTING.ja-JP.md) | [한국어](CONTRIBUTING.ko-KR.md) | Русский
|
||
|
||
## Кодекс поведения
|
||
|
||
Участвуя в этом проекте, вы соглашаетесь поддерживать уважительную и инклюзивную атмосферу. Пожалуйста, будьте доброжелательны и конструктивны в любом взаимодействии.
|
||
|
||
## Как можно помочь
|
||
|
||
Помимо написания кода, есть много способов внести вклад:
|
||
|
||
- **Сообщайте о багах** — нашли поломку? Заведите issue с шагами воспроизведения.
|
||
- **Предлагайте улучшения** — есть идея? Начните обсуждение в [GitHub Discussions](https://github.com/alibaba/open-code-review/discussions/categories/ideas) или заведите issue [Feature Request](https://github.com/alibaba/open-code-review/issues/new?template=feature_request.yml).
|
||
- **Улучшайте документацию** — исправляйте опечатки, проясняйте формулировки, добавляйте примеры. Чтобы сообщить о проблеме, можно также завести [Documentation Issue](https://github.com/alibaba/open-code-review/issues/new?template=docs_report.yml).
|
||
- **Ревьюйте pull request'ы** — помогайте нам проверять код других контрибьюторов.
|
||
- **Пишите код** — исправляйте баги, добавляйте функциональность, улучшайте производительность.
|
||
|
||
## С чего начать
|
||
|
||
### Требования
|
||
|
||
- [Go 1.25+](https://go.dev/dl/)
|
||
- [Git](https://git-scm.com/)
|
||
- [Make](https://www.gnu.org/software/make/)
|
||
|
||
### Настройка
|
||
|
||
```bash
|
||
# 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`:
|
||
|
||
```bash
|
||
git checkout main
|
||
git pull upstream main
|
||
git checkout -b feat/your-feature-name
|
||
```
|
||
|
||
Используйте префиксы, обозначающие тип изменения:
|
||
|
||
| Префикс | Назначение |
|
||
| ----------- | --------------------------------------- |
|
||
| `feat/` | Новая функциональность |
|
||
| `fix/` | Исправление бага |
|
||
| `docs/` | Только документация |
|
||
| `refactor/` | Рефакторинг (без изменения поведения) |
|
||
| `test/` | Добавление или обновление тестов |
|
||
| `chore/` | Сборка, CI или инструментарий |
|
||
|
||
### Сообщения коммитов
|
||
|
||
Следуйте формату [Conventional Commits](https://www.conventionalcommits.org/):
|
||
|
||
```
|
||
<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. После создания новых файлов выполните:
|
||
|
||
```bash
|
||
make license-add
|
||
```
|
||
|
||
Эта команда автоматически добавит необходимый заголовок. CI отклонит PR с отсутствующими заголовками.
|
||
|
||
### Качество кода
|
||
|
||
Перед отправкой изменений убедитесь, что они проходят все проверки:
|
||
|
||
```bash
|
||
# Форматирование, линт и проверка заголовков лицензии
|
||
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-обёртка
|
||
```
|
||
|
||
## Вклад в документацию
|
||
|
||
Документация — важнейшая часть 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](https://github.com/alibaba/open-code-review/issues/new?template=docs_report.yml).
|
||
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`](https://github.com/alibaba/open-code-review/labels/good%20first%20issue) — небольшие, хорошо очерченные задачи, идеальные для старта.
|
||
- [`help wanted`](https://github.com/alibaba/open-code-review/labels/help%20wanted) — задачи, где мы будем рады помощи сообщества.
|
||
|
||
С чего удобно начать:
|
||
|
||
- Улучшение сообщений об ошибках и вывода CLI
|
||
- Написание тестов для непокрытых участков кода
|
||
- Улучшение документации
|
||
|
||
## Сообщество
|
||
|
||
- **Сообщения о багах** — [GitHub Issues](https://github.com/alibaba/open-code-review/issues)
|
||
- **Предложения функциональности** — [GitHub Discussions (Ideas)](https://github.com/alibaba/open-code-review/discussions/categories/ideas) или issue [Feature Request](https://github.com/alibaba/open-code-review/issues/new?template=feature_request.yml)
|
||
- **Вопросы и помощь** — если у вас есть вопросы об использовании OpenCodeReview, задавайте их в [GitHub Discussions](https://github.com/alibaba/open-code-review/discussions)
|
||
|
||
## Лицензия
|
||
|
||
Внося вклад в OpenCodeReview, вы соглашаетесь с тем, что ваш вклад будет лицензирован на условиях [Apache License 2.0](LICENSE).
|