Это руководство предназначено для тех, кто хочет внести свой вклад в проект Discourse с открытым исходным кодом. В нём подробно описывается настройка среды разработки и соглашения, необходимые для эффективного сотрудничества.
Требуемый уровень пользователя: Хотя код может вносить любой желающий, вам необходимо хорошо разбираться в Ruby и JavaScript.
Краткое содержание
В этой документации рассматриваются следующие вопросы:
- Настройка среды разработки
- Понимание того, с чего начать внесение вклада
- Создание и работа с плагинами Discourse
- Вклад в ядро Discourse
- Соглашения по написанию кода
- Отправка ваших изменений на GitHub
Настройка среды разработки
Прежде чем начать вносить изменения, убедитесь, что ваша среда разработки настроена правильно. Следуйте соответствующему руководству для вашей платформы:
- Все платформы: Установка Discourse для разработки с помощью Docker
- Mac OS X: Руководство для начинающих по установке Discourse на macOS для разработки
- Linux (Ubuntu): Руководство для начинающих по установке Discourse на Ubuntu для разработки
- Windows: Руководство для начинающих по установке Discourse на Windows 10 для разработки
С чего начать
Discourse — это большой проект, и понимание его базовых технологий, таких как Ruby и JavaScript, является обязательным. За рекомендациями о том, как начать, обратитесь к руководству для новичков.
Создание и работа с плагинами
Плагины позволяют изучать внутренние механизмы Discourse небольшими порциями и легко начать вносить код. Начните с:
- Developing Discourse Plugins - Part 1 - Create a basic plugin
- (deprecated) Plugin outlet locations theme component
Для вдохновения изучите популярные идеи в каналах Contribute > Feature и Customization > Extras.
Вклад в ядро Discourse
Код ядра Discourse управляется в репозитории core на GitHub.
Подписание CLA
Перед тем как вносить изменения, прочтите и подпишите Электронное соглашение о лицензии на вклад в форумы Discourse. Команда не может юридически принять pull-запросы (PR) от пользователей, не подписавших CLA.
Разминка со стартовыми задачами
Изучите тег pr-welcome для поиска хороших задач для начала работы.
Работа со списком ошибок
Исправляйте ошибки из списка открытых ошибок, отсортированного по количеству лайков. Оставьте заметку, если работаете над ошибкой — если вы не завершите работу, оставьте любые соответствующие заметки, чтобы кто-то другой мог продолжить её.
Помощь с темами функций
Добавляйте детали и макеты к запросам на новые функции, чтобы помочь в процессе их утверждения. Помните, что не каждая функция будет включена в ядро.
Улучшение производительности
Мы приветствуем pull-запросы, которые повышают производительность на стороне клиента или сервера, уделяя особое внимание областям с высоким воздействием, таким как начальная загрузка главной страницы или просмотр темы.
Улучшение проектов, поддерживаемых Discourse
Внесите свой вклад в другие проекты с открытым исходным кодом, поддерживаемые Discourse. Некоторые из них:
- Logster — веб-интерфейс для просмотра логов
- Message Bus — движок для взаимодействия с сайтом в реальном времени
- Rack Mini Profiler — инструмент диагностики
- Discourse API — клиент API
- Discourse Docker — движок распространения Discourse
- WP Discourse — плагин для WordPress
- Memory Profiler — профилировщик для Ruby
- Ember Performance — набор тестов производительности для Ember
Соглашения по написанию кода
Именование КРИТИЧЕСКИ ВАЖНО
Стремитесь к 100% совпадению терминов, используемых на сайте, с именами классов и столбцов в базе данных (например, «posts»).
Совместимость с последними версиями зависимостей КРИТИЧЕСКИ ВАЖНА
Убедитесь в совместимости с последними стабильными выпусками библиотек, таких как Rails, Ruby и Ember. Проверяйте наличие регрессий при обновлении зависимостей.
Вклады, состоящие только из тестов, приветствуются
Вклады, состоящие только из тестов, приветствуются, особенно для процессов и действий контроллеров, которые не покрыты тестами. Избегайте моков, если это абсолютно не необходимо.
Вклады, состоящие только из рефакторинга, НЕ приветствуются
Избегайте отправки pull-запросов, содержащих только рефакторинг. Вместо этого исправьте ошибку или реализуйте функцию, одновременно улучшая код.
Отправка кода на GitHub
Пошаговый рабочий процесс
-
Клонируйте репозиторий Discourse:
git clone https://github.com/discourse/discourse.git -
Создайте новую ветку:
cd discourse git checkout -b new_discourse_branch -
Написание кода:
- Соблюдайте существующие соглашения по написанию кода, которые вы найдете в коде.
- Включите тесты и убедитесь, что они проходят.
- Ссылка на соответствующие обсуждения на мета-форуме Discourse.
-
Соблюдайте соглашения по написанию кода:
- два пробела, без табуляций
- без конечных пробелов, пустые строки не должны содержать пробелов
- используйте пробелы вокруг операторов, после запятых, двоеточий, точек с запятой, вокруг
{и перед} - без пробела после
(,[или перед],) - используйте синтаксис хешей Ruby 1.9: предпочитайте
{ a: 1 }вместо{ :a => 1 } - предпочитайте
class << self; def method; endвместоdef self.methodдля методов класса - предпочитайте
{ ... }вместоdo ... endдля однострочных блоков, избегайте использования{ ... }для многострочных блоков - избегайте
return, если это не требуется
-
Коммит:
git commit -m "Краткое описание изменения" -m "Подробное описание изменения"Никогда не оставляйте сообщение коммита пустым — это полезное руководство по написанию сообщений коммитов. Сообщение должно начинаться с краткого (максимум 72 символа) описания в первой строке, за которым следует пустая строка, а затем более подробное описание изменения. При необходимости можно использовать синтаксис markdown для простого форматирования.
Обязательно префиксируйте названия коммитов в соответствии с соглашениями Discourse.
5 (a). Линтинг:
JavaScript-код линтуется с помощью eslint и форматируется с помощью prettier. Ruby линтуется с помощью RuboCop и форматируется с помощью Syntax Tree. SCSS/CSS линтуется с помощью stylelint. Шаблоны Ember линтуются с помощью ember-template-lint. Все эти проверки автоматически запускаются в GitHub Actions при создании pull-запроса для Discourse.- Настоятельно рекомендуется установить наши git-хуки pre-commit с помощью
lefthook. Это будет запускаться автоматически при каждом коммите в ядре Discourse и выявлять проблемы с различными языками и шаблонами до того, как вы отправите их и будете ждать запуска CI в GitHub. Запустите это в корневой папке вашего проекта:pnpm lefthook install
- Настоятельно рекомендуется установить наши git-хуки pre-commit с помощью
-
Обновите вашу ветку:
git fetch origin git rebase origin/main -
Форк:
git remote add mine git@github.com:<your-username>/discourse.git -
Отправьте в удалённый репозиторий:
git push mine new_discourse_branch -
Создайте pull-запрос:
- Перейдите в ваш репозиторий на GitHub.
- Нажмите «Pull Request».
- Введите имя вашей ветки в поле ветки.
- Нажмите «Update Commit Range».
- Проверьте изменения во вкладках «Commits» и «Files Changed».
- Укажите заголовок и описание.
- Нажмите «Send pull request».
Перед отправкой pull-запроса очистите историю, просмотрите свои коммиты и объедините мелкие изменения и исправления в соответствующие коммиты. Вы можете объединить коммиты с помощью интерактивного ребейса:
git fetch origin
git checkout new_discourse_branch
git rebase origin/main
git rebase -i
< редактор открывается и позволяет изменить историю коммитов >
< следуйте инструкциям внизу редактора >
git push -f mine new_discourse_branch
- Реагируйте на обратную связь:
- Будьте отзывчивы к отзывам и готовы внедрить предлагаемые изменения.
- Помните, что обратная связь означает, что ваша работа ценится и предназначена для включения.
Спасибо за вклад в проект Discourse с открытым исходным кодом!