Внести вклад в код

Вклад в код начинается с чёткой проблемы. Перед исправлением дефекта сначала убедитесь, что его можно воспроизвести; перед добавлением функции сначала опишите сценарий пользователя и ожидаемое поведение. Для крупных изменений рекомендуется сначала согласовать направление в GitHub Issue или Discussion.

Один вклад решает только одну чёткую проблему; сначала выполните локальную проверку, затем отправляйте на ревью.

Перед началом

Репозиторий Cherry Studio

Исходный код, README и вход для разработки

GitHub Issues

Дефекты, предложения функций и вопросы, требующие решения

Руководство по вкладу

Требования к веткам, тестированию, подписанию и ревью

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

Границы сотрудничества в сообществе

Подходящие для начала задачи можно найти по good first issue、help wanted и kind/bug в виде меток. Перед тем как начать, напишите в Issue, что именно вы собираетесь делать, чтобы избежать дублирования работы несколькими людьми.

Какую ветку выбрать

Большинство текущих функций, исправлений, рефакторинга и оптимизаций отправляются в main. Если Issue, указания сопровождающих или руководство по вкладу указывают другую целевую ветку, ориентируйтесь на описание проекта на тот момент; не судите только по старым инструкциям.

Не определяйте целевую ветку по старым инструкциям. Перед созданием PR ещё раз проверьте текущее руководство по вкладу и шаблон PR в репозитории; если политика веток изменилась, ориентируйтесь на содержимое репозитория.

Когда подходит вклад в код

Ситуация	Рекомендуемый способ
Проблемы, которые стабильно воспроизводятся	Сначала отправьте минимальное исправление и соответствующую проверку
Небольшие функции с чёткими границами	Сначала подтвердите требования и целевую ветку, затем начинайте реализацию
Связано с миграцией данных, правами доступа или архитектурой	Сначала согласуйте решение в Issue или Discussion
Нужно только изменить документацию или скриншоты	Идите по пути【вклад в документацию】, не смешивайте это с кодовым PR

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

Процесс отправки

1

1. Сделайте fork и создайте ветку

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

2

2. Подготовьте среду разработки

Следуя 【Developer Guide】 репозитория, установите указанные версии Node.js и pnpm, выполните pnpm install. Перед началом изменений сначала запустите существующие проверки, относящиеся к целевому модулю, чтобы убедиться, что базовое состояние работоспособно.

3

3. Измените и проверьте

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

4

4. Сделайте коммит и подпишите

В сообщении коммита укажите тип изменения и модуль, и используйте git commit --signoff для добавления DCO-подписи. Подпись означает, что вы имеете право отправлять этот материал в соответствии с лицензией проекта.

5

5. Создайте PR

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

После отправки PR

PR от новых участников сначала будут иметь needs-ok-to-test, и автоматические тесты не начнутся сразу. После подтверждения участником репозитория будет использован /ok-to-test для запуска pipeline. Draft PR не назначается на обычное ревью и также пропускает автоматические тесты; когда всё готово, отметьте его как Ready for review.

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

Самопроверка перед отправкой

• Целевая ветка верна;
• Объём изменений соответствует описанию в Issue/PR;
• Для нового поведения есть тесты или воспроизводимые шаги ручной проверки;
• Пользовательские изменения синхронно отражены в документации;
• Учтены миграция данных, обновление и совместимость;
• Не были отправлены API Key, реальные данные пользователей или файлы отладки;
• Коммит подписан, Release Note соответствует требованиям шаблона.

Нужен ли Issue даже для небольших изменений?

Опечатки и очевидные мелкие исправления можно отправлять напрямую; если речь идёт о поведении продукта, архитектуре или более значительном объёме работы, сначала лучше открыть Issue, чтобы согласовать направление. Нужен ли Issue, определяется текущими правилами сопровождения репозитория.

Почему CI не запустился автоматически?

Сначала убедитесь, что PR не в состоянии Draft. Для PR от новых участников требуется, чтобы участник репозитория /ok-to-test, увидев needs-ok-to-test , терпеливо дождался подтверждения в PR.