Вклад в open source

В этой статье вы узнаете, как внести вклад в проект с open source, проработав пример. Мы поможем вам внести свой вклад github/docs в репозиторий: знакомство с репозиторием, поиск области для участия, отправки и отправки запроса на вытягивание, а также работы со службами поддержки для принятия изменений.

Ориентирование на себя с помощью рекомендаций по проекту

Прежде чем начать, важно понять рекомендации и требования проекта.

Почему важны рекомендации?

Каждый проект имеет собственные соглашения, стандарты кодирования и процессы вклада, которые необходимо выполнить.

• Требования к стилю кода и форматированию: форматирование кода, соглашения об именовании и правилах подстраивание
• Рекомендации по тестированию: как выполнять тесты, какие тесты требуются для новых функций и соглашений о тестировании
• Процесс запроса на вытягивание: структура запроса на вытягивание, сведения, которые необходимо включить, и проверить ожидания
• Настройка разработки: настройка локальной среды разработки, необходимых зависимостей и процессов сборки
• Отчеты о проблемах: как сообщать об ошибках, функциях запроса или задавать вопросы
• Каналы коммуникации: где задавать вопросы, обсуждать изменения или получать помощь от обслуживающих

Время, чтобы прочитать эти данные, сэкономит время, как для вас, так и для хранителей, и сделать его более вероятным, что ваш вклад будет принят.

Поиск рекомендаций

Чтобы получить доступ к этим рекомендациям и требованиям, перейдите в контрольный список "Стандарты сообщества" на вкладке "Аналитика ". В нашем примере мы будем использовать github/docs стандарты сообщества.

• README: предоставляет общие сведения о проекте. Содержимое может отличаться, но README помогает пользователям и участникам быстро понять, что такое проект и как его использовать, а также ссылки на другую документацию.

• Кодекс поведения: определяет допустимые стандарты поведения для участников проекта и членов сообщества, а также устанавливает ожидания и процедуры для устранения нарушений.

• Участие. Предоставляет рекомендации и инструкции для участников проекта. Это помогает упростить процесс вклада, задав четкие ожидания и поощряя последовательную совместную работу.

• Лицензия: юридически определяет, как другие могут использовать, изменять и распространять код, защищая как обслуживающих, так и пользователей, устанавливая четкие условия для авторских прав и разрешений.

  • Например, github/docs репозиторий использует лицензию Creative Commons для документации, которая является типом лицензии, специально предназначенной для творческих работ. Код github/docs программного обеспечения находится под лицензией MIT, которая является разрешительной лицензией, которая позволяет любому пользователю использовать код, содержащийся в нем.
  • Вы можете узнать о других распространенных типах лицензий с помощью средства выбора лицензии .

• Политика безопасности. Предоставляет инструкции по созданию отчетов об уязвимостях безопасности для обслуживания репозитория.

Просмотрите все ресурсы, доступные для github/docs репозитория.

Поиск области для участия

При первом участии в проекте, начиная с незначительных исправлений, таких как улучшения документации или небольшие отчеты об ошибках, можно ознакомиться с рабочей процессом базы кода и участника. В этом примере вы будете искать проблемы с помощью help wanted меток и good first issue меток для решения конкретных проблем, открытых для внешних участников. Затем вы будете использовать Copilot для предоставления контекста о проблеме.

1. Перейдите на ****" репозитория, а затем используйте github/docs и выберите "Нужная помощь", чтобы просмотреть открытые проблемы, которые поддержку специально помечают как нуждающиеся в помощи сообщества.

2. Просмотрите список проблем и найдите интересующий вас вопрос.

3. Перейдите к https://github.com/copilot.

4. В поле запроса введите следующую строку:

   Text

   Can you summarize the key points and next steps from this issue?
   

5. Прочитайте контекст Copilot и комментарии других участников и поддержку, чтобы узнать, является ли проблема одной из них. Если у вас есть конкретные вопросы, вы можете задать непосредственно в этой проблеме или в дискорде проекта, IRC или Slack, если применимо.

Создание собственной копии проекта

Теперь вы готовы приступить к участию. Так как у вас нет доступа к редактированию репозитория, сначала необходимо создать вилку: собственную копию репозитория, где можно безопасно вносить изменения и отправлять их обратно для проверки обслуживания. В этом примере мы рассмотрим создание вилки репозитория github/docs .

1. Перейдите к проекту GitHub Docs на https://github.com/github/docs.

2. В правом верхнем углу страницы щелкните Вилка.

3. В разделе "Владелец" выберите раскрывающееся меню и щелкните владельца для вилированного репозитория.

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

5. При необходимости в поле "Описание" введите описание вилки.

6. При необходимости выберите " Копировать только ветвь DEFAULT".

   Для многих сценариев разветвления, таких как участие в проектах с открытым кодом, необходимо скопировать только ветвь по умолчанию. Если этот параметр не выбран, все ветви будут скопированы в новую вилку.

7. Нажмите Создать вилку.

Клонирование вилки проекта

Теперь у вас есть вилка репозитория github/docs в вашей учетной записи, но вам нужно получить его на локальный компьютер, чтобы приступить к работе с изменениями.

1. В GitHubперейдите к вилку репозитория github/docs .

2. Над списком файлов щелкните Code.

   

3. Скопируйте URL-адрес репозитория.

   • Чтобы клонировать репозиторий с помощью HTTPS, в разделе "HTTPS" нажмите .

   • Чтобы клонировать репозиторий с помощью ключа SSH, включая сертификат, выданный центром сертификации SSH вашей организации, щелкните SSH, а затем щелкните .

   • Чтобы клонировать репозиторий с помощью GitHub CLI, щелкните GitHub CLI, а затем щелкните .

     

4. В Mac или Linux откройте терминал. В Windows откройте Git Bash.

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

6. Введите git clone, а затем вставьте URL-адрес, скопированный ранее. Это будет выглядеть следующим образом: вместо имени пользователя GitHub :YOUR-USERNAME

   Shell

   git clone https://github.com/YOUR-USERNAME/docs
   

7. Нажмите клавишу ВВОД. Будет создан локальный клон.

Внесение изменений в ветвь раздела

Теперь пришло время внести изменения! Перед началом работы рекомендуется создать ветвь раздела с описательным именем в вилке. Использование ветви разделов позволяет сохранять работу отдельно от ветвь по умолчанию репозитория.

git checkout -b YOUR_TOPIC_BRANCH

git checkout -b YOUR_TOPIC_BRANCH

После переключения в ветвь раздела откройте любимый текстовый редактор или интегрированную среду разработки и начните писать код. Следуйте приведенным далее рекомендациям.

• Используйте Copilot для предоставления предложений кода, что дает вам уверенность в изменениях.
• Задокументируйте код и напишите тесты. Это часто не учитывается и может помочь обеспечить объединение вашего вклада.
• Попросите Copilot вопросы об этой проблеме, чтобы получить более подробные сведения о требованиях к реализации.
• Используйте Copilot для проверки изменений, чтобы убедиться, что они соответствуют стилю кода проекта и требованиям к документации.
• Используйте Copilot для получения инструкций по созданию и тестированию проекта на локальном компьютере.

Фиксация и отправка изменений

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

git add .
git commit -m "a short description of the change"

git add .
git commit -m "a short description of the change"

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

git push

git push

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

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

1. Зайдите в свой форкированный репозиторий на GitHub. Например: https://github.com/YOUR-USERNAME/docs.
2. Появится запрос на сравнение и запрос на вытягивание для недавно отправленной ветви. Нажмите ее.
3. В противном случае перейдите на вкладку "Запросы на вытягивание" и нажмите кнопку "Создать запрос на вытягивание".
4. Убедитесь, что базовый **** репозиторий находитсяgithub/docs, и базовая ветвь является их основной ветвью (например, main).
5. Убедитесь, что головной** репозиторий **является вашим вилкой (YOUR-USERNAME/docs) и ветвь сравнения является вашей ветвью.
6. Введите название и описание для запроса на вытягивание. В описании обратитесь к проблеме, в которую будет закрыт запрос на вытягивание. Например: Closes: #15. Это обеспечит контекст запроса на вытягивание и автоматически закрывает проблему после объединения запроса на вытягивание.

Работа с обслуживателями проектов

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

• Когда обратная связь поступает о запросе на вытягивание, реагировать быстро и профессионально, даже если критика чувствует себя жесткой. Обслуживающие специалисты обычно ориентированы на качество кода.
• Если изменения запрашиваются для запроса на вытягивание, не открывайте новый запрос на вытягивание, чтобы устранить изменения. Сохранение существующего запроса на вытягивание и внесение изменений в нее помогает предотвратить потерю контекста хранителями.
• Если запрос на вытягивание остается незамеченным в течение нескольких недель, вежливо следите за комментарием, запрашивающим отзыв. ** Не упоминайте **непосредственно дескрипторы обслуживания. Сопровождающие часто балансируют между работой с open source и полными обязанностями, а понимание ограничений по времени способствует лучшему сотрудничеству.
• Если ваш вклад не принимается, попросите поддержку отзывов, чтобы вы могли иметь этот контекст в следующий раз, когда вы хотите внести вклад.

Следующие шаги

Теперь вы знаете, как определить правильные проблемы для работы, создать вклады, которые поддержку хотят объединить, и как перейти к процессу проверка запроса на вытягивание. Сообщество open source на GitHub готово принять ваш уникальный взгляд и навыки. Найдите новый проект, который возбуждает вас, определите проблему для работы и начните вносить свой вклад.