Руководство по внесению вклада

Мы рады вашему интересу внести вклад в наш проект. Чтобы упростить процесс, мы подготовили подробное пошаговое руководство ниже.

TIP

Для удобства управления своими изменениями мы рекомендуем использовать GitHub Desktop — графический клиент GitHub.

Форк и клонирование репозитория

Выполните следующие шаги, чтобы сделать форк репозитория, клонировать его, создать новую ветку и настроить локальную среду разработки:

1. Перейдите на страницу проекта на GitHub по этой ссылке
2. Нажмите Fork в правом верхнем углу. Это создаст копию репозитория в вашей учётной записи GitHub
3. Откройте GitHub Desktop.
4. В верхнем меню GitHub Desktop выберите File > Clone Repository....
5. В категории GitHub.com вы должны увидеть форкнутый репозиторий.
6. Чтобы клонировать репозиторий, нажмите Clone.
7. После завершения клонирования перейдите в Current Branch и выберите New Branch. Введите понятное имя для новой ветки.

WARNING

Ветка main защищена. Прямое редактирование в ней недопустимо. Всегда создавайте новую ветку для своих изменений.

8. Перейдите в каталог airreps в локальной среде.
9. Откройте проект в среде разработки (IDE) на ваш выбор. Мы рекомендуем Visual Studio Code — функциональную бесплатную IDE. Также можно использовать IDE на базе ИИ, такие как Cursor или Antigravity от Google, которые значительно упрощают вклад благодаря подсказкам по коду и документации.

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

Выберите один из двух вариантов настройки среды разработки:

Вариант 1 (Рекомендуемый)

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

1. Установите Bun. В этом проекте Bun используется как пакетный менеджер и среда выполнения.
2. Установите Node.js. Рекомендуется LTS-версия с долгосрочной поддержкой.
3. После установки откройте терминал внутри IDE и выполните следующую команду:

bun install

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

bun run docs:dev

5. В терминале появится локальный URL, например http://localhost:5173. Откройте этот адрес в браузере, чтобы увидеть документацию. Страница автоматически обновляется при изменении исходных файлов.

Вариант 2

Этот способ позволяет работать напрямую с markdown-файлами, хотя он может неточно отображать некоторые возможности VitePress.

1. Откройте Visual Studio Code или предпочитаемую IDE.
2. Установите расширение Markdown Preview Enhanced для Visual Studio Code. Его можно найти на вкладке Extensions в боковой панели.
3. Откройте любой markdown-файл из директории docs.
4. Чтобы открыть предпросмотр Markdown, вызовите палитру команд: Ctrl + Shift + P (Windows) или Cmd + Shift + P (Mac).
5. Найдите Markdown Preview и выберите Markdown: Open Preview.

WARNING

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

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

Когда изменения готовы, выполните следующие шаги для отправки на ревью:

1. Если вы выбрали Вариант 1 из раздела Настройка среды разработки, убедитесь, что страницы корректно собираются, выполнив следующую команду:

bun run docs:build

DANGER

Если в выводе появится сообщение Command failed или другая ошибка, значит есть проблема. Сообщение об ошибке должно дать понимание сути. Если вы не уверены, обратитесь к нашим сотрудникам в Discord-сервере.

2. Откройте GitHub Desktop. На левой панели будет показано количество изменённых файлов.
3. Вы можете просмотреть изменения по каждому файлу. Выберите файл и заполните поле Summary (required). При необходимости добавьте подробности в поле Description. Нажмите Commit to the branch you created, чтобы зафиксировать изменения.
4. Затем нажмите Push changes to x (где x — имя созданной вами ветки), чтобы загрузить изменения на GitHub.

TIP

Если вы зафиксировали все файлы — отлично! Следующий шаг — отправить изменения на GitHub и создать Pull Request.

Создание Pull Request

Выполните следующие шаги, чтобы создать pull request и предложить слияние ваших изменений в основную ветку:

1. После того как все изменения зафиксированы и отправлены в удалённую ветку, пора создавать pull request.
2. Перейдите в свой форкнутый репозиторий на сайте GitHub.
3. Нажмите New pull request. Вас перенаправят на страницу исходного репозитория.
4. Убедитесь, что базовый репозиторий — base: main, а исходный — <your_username>/<your_branch_name>.
5. Просмотрите изменения и заполните форму с понятным описанием того, что и зачем вы изменили. Для примера можно посмотреть этот образцовый pull request.
6. Нажмите Create pull request.
7. После отправки pull request GitHub Actions попытается собрать ваши изменения, чтобы выявить проблемы. Если проблем нет, участник репозитория проверит изменения и либо примет их, либо запросит правки.

Чем можно помочь?

После успешного слияния ваш профиль GitHub автоматически будет включён в раздел Contributors в нижней части главной страницы. Если по какой-то причине вы предпочитаете, чтобы профиль не отображался в этом разделе, обратитесь к одному из наших сотрудников для удаления профиля.

• Исправить опечатки или ошибки — Заметили неточность? Отправьте быстрое исправление!
• Обновить устаревшую информацию — Помогите поддерживать руководство в актуальном состоянии
• Добавить новый контент — Документируйте новые дополнения, функции или конфигурации
• Улучшить ясность — Сделайте объяснения проще для понимания
• Добавить скриншоты — Визуальные руководства всегда полезны
• Предложить улучшения — Есть идеи? Откройте issue для обсуждения

Спасибо за ваш вклад в улучшение нашего проекта!