Руководство по участию

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

TIP

Для удобства управления вашими вкладами мы рекомендуем использовать GitHub Desktop, GUI-клиент для 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 или Google's Antigravity, которые могут значительно упростить участие, помогая с предложениями кода и документацией.

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

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

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

Для настройки оптимальной среды разработки:

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

bun install

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

bun run docs:dev

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

Вариант 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, а головной репозиторий — <ваш_логин>/<имя_вашей_ветки>.
5. Просмотрите свои изменения и заполните форму с чётким описанием того, что вы изменили и почему. для справки; вы можете ознакомиться с этим примерным pull request.
6. Нажмите Create pull request.
7. После отправки pull request GitHub Actions попытается собрать ваши изменения для обнаружения любых проблем. Если проблем нет, участник репозитория рассмотрит ваши изменения и либо объединит их, либо запросит дополнительные изменения.

Чем вы можете помочь?

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

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

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