Как создать запрос на слияние на GitHub

Введение

Git — это распределенная система управления версиями с открытым исходным кодом, которая упрощает управление совместными программными проектами. Многие проекты хранят свои файлы в репозитории Git, а такие платформы, как GitHub, сделали совместное использование кода доступным, ценным и эффективным.

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

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

Предпосылки

У вас должен быть установлен Git на вашем локальном компьютере. Вы можете проверить, установлен ли Git на вашем компьютере, и пройти процесс установки для вашей операционной системы, следуя этому руководству.

Вам также необходимо иметь или создать учетную запись GitHub. Вы можете сделать это через веб-сайт GitHub, github.com, и можете либо войти в систему, либо создать свою учетную запись.

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

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

Создать копию репозитория

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

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

Разветвить репозиторий

Вы можете разветвить репозиторий на GitHub, перейдя в браузере по URL-адресу GitHub проекта с открытым исходным кодом, в который вы хотели бы внести свой вклад.

URL-адреса репозитория GitHub будут ссылаться как на имя пользователя, связанное с владельцем репозитория, так и на имя репозитория. Например, сообщество DigitalOcean (имя пользователя: do-community) является владельцем репозитория проекта cloud_haiku, поэтому URL-адрес GitHub для этого проекта:

https://github.com/do-community/cloud_haiku

В приведенном выше примере do-community — это имя пользователя, а cloud_haiku — имя репозитория.

После того, как вы определили проект, в который хотели бы внести свой вклад, вы можете перейти к URL-адресу, который будет иметь следующий формат:

https://github.com/username/repository

Или вы можете найти проект с помощью панели поиска GitHub.

Когда вы находитесь на главной странице репозитория, кнопка Fork будет отображаться в верхней правой части страницы под значком пользователя:

Нажмите кнопку «Разветвление», чтобы начать процесс разветвления. В окне вашего браузера вы получите уведомление о том, что репозиторий, который вы разветвляете, обрабатывается:

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

Итак, в приведенном выше примере вместо do-community/cloud_haiku в верхней части страницы вы увидите your-username/cloud_haiku, а новый URL-адрес будет выглядеть следующим образом:

https://github.com/your-username/cloud_haiku

Разветвив репозиторий, вы готовы клонировать его, чтобы у вас была локальная рабочая копия базы кода.

Клонировать репозиторий

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

Мы будем использовать команду git clone вместе с URL-адресом, указывающим на ваш форк репозитория.

Этот URL-адрес будет аналогичен приведенному выше URL-адресу, за исключением того, что теперь он будет заканчиваться на .git. В приведенном выше примере cloud_haiku URL-адрес будет выглядеть примерно так, а ваше фактическое имя пользователя заменит your-username:

https://github.com/your-username/cloud_haiku.git

В качестве альтернативы вы можете скопировать URL-адрес, используя зеленую кнопку \⤓ Код со страницы вашего репозитория, которую вы разветвили из исходной страницы репозитория. После нажатия кнопки вы сможете скопировать URL-адрес, нажав кнопку буфера обмена рядом на URL:

Получив URL-адрес, мы готовы клонировать репозиторий. Для этого мы объединим команду git clone с URL-адресом репозитория из командной строки в окне терминала:

git clone https://github.com/your-username/repository.git

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

Создать новую ветку

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

Основная ветвь репозитория проекта обычно называется основной ветвью. Рекомендуемая практика — рассматривать что-либо в основной ветке как развертываемое для использования другими в любое время.

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

При создании ветки на основе существующего проекта очень важно создать новую ветку вне основной ветки. Вы также должны убедиться, что имя вашей ветки является описательным. Вместо того, чтобы называть его my-branch, вы должны использовать что-то вроде frontend-hook-migration или fix-documentation-typos.

Чтобы создать ветку из нашего окна терминала, давайте изменим наш каталог, чтобы мы работали в каталоге репозитория. Обязательно используйте фактическое имя репозитория (например, cloud_haiku), чтобы перейти в этот каталог.

cd repository

Теперь мы создадим нашу новую ветку с помощью команды git branch. Убедитесь, что вы назвали его описательно, чтобы другие, работающие над проектом, поняли, над чем вы работаете.

git branch new-branch

Теперь, когда наша новая ветка создана, мы можем переключиться, чтобы убедиться, что мы работаем с этой веткой, с помощью команды git checkout:

git checkout new-branch

После ввода команды git checkout вы получите следующий вывод:

Output
Switched to branch 'new-branch'

Кроме того, вы можете объединить две приведенные выше команды, создав новую ветку и переключившись на нее, с помощью следующей команды и флага -b:

git checkout -b new-branch

Если вы хотите вернуться к main, вы будете использовать команду checkout с именем основной ветки:

git checkout main

Команда checkout позволит вам переключаться между несколькими ветвями, поэтому потенциально вы можете работать с несколькими функциями одновременно.

На этом этапе вы можете изменять существующие файлы или добавлять новые файлы в проект в своей собственной ветке.

Внесите изменения локально

Чтобы продемонстрировать выполнение запроса на вытягивание, давайте воспользуемся примером репозитория cloud_haiku и создадим новый файл в нашей локальной копии. Используйте предпочитаемый вами текстовый редактор, чтобы создать новый файл, чтобы мы могли добавить новое стихотворение хайку, как описано в правилах. Например, мы можем использовать nano и назвать файл нашего примера filename.md. Вам нужно будет назвать свой файл оригинальным именем с расширением .md для Markdown.

nano filename.md

Далее мы добавим текст в новый файл, следуя рекомендациям по внесению вклада. Нам нужно будет использовать формат Jekyll и добавить хайку с разрывами строк. Следующий файл является примером файла, так как вам нужно добавить оригинальное хайку.

---
layout: haiku
title: Octopus Cloud
author: Sammy
---

Distributed cloud <br>
Like the octopuses' minds <br>
Across the network <br>

После включения текста сохраните и закройте файл. Если вы использовали nano, сделайте это, нажав CTRL + X, затем Y, а затем ENTER.

После того как вы изменили существующий файл или добавили новый файл в выбранный вами проект, вы можете разместить его в своем локальном репозитории, что мы можем сделать с помощью команды git add. В нашем примере filename.md мы введем следующую команду.

git add filename.md 

Мы передали имя созданного нами файла этой команде, чтобы разместить его в нашем локальном репозитории. Это гарантирует, что ваш файл готов к добавлению.

Если вы хотите добавить все файлы, которые вы изменили, в определенный каталог, вы можете подготовить их все с помощью следующей команды:

git add . 

Здесь точка или точка добавит все соответствующие файлы.

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

git add -A

Или, в качестве альтернативы, вы можете ввести git add -all для всех новых файлов, которые будут подготовлены.

Когда наш файл подготовлен, мы захотим записать изменения, которые мы внесли в репозиторий, с помощью команды git commit.

Зафиксировать изменения

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

Если у нас есть очень короткое сообщение, мы можем записать его с помощью флага -m и заключить сообщение в кавычки. В нашем примере с добавлением хайку наш git commit может быть похож на следующий.

git commit -m "Added a new haiku in filename.md file"

Если это не незначительное или ожидаемое изменение, мы можем захотеть включить более длинное сообщение о коммите, чтобы наши соавторы были полностью в курсе нашего вклада. Чтобы записать это большое сообщение, мы запустим команду git commit, которая откроет текстовый редактор по умолчанию:

git commit

При выполнении этой команды вы можете заметить, что находитесь в редакторе vim, который можно закрыть, набрав :q. Если вы хотите настроить текстовый редактор по умолчанию, вы можете сделать это с помощью команды git config и установить nano в качестве редактора по умолчанию, например:

git config --global core.editor "nano"

Или вим:

git config --global core.editor "vim"

После запуска команды git commit, в зависимости от используемого вами текстового редактора по умолчанию, в окне терминала должен отображаться готовый для редактирования документ, который будет похож на этот:

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch new-branch
# Your branch is up-to-date with 'origin/new-branch'.
#
# Changes to be committed:
#       modified:   new-feature.py
#

Под вводными комментариями вы должны добавить сообщение фиксации в текстовый файл.

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

Отправить изменения

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

git status

В зависимости от внесенных изменений вы получите вывод, подобный этому:

Output
On branch new-branch
nothing to commit, working tree clean

На этом этапе вы можете использовать команду git push, чтобы отправить изменения в текущую ветку вашего разветвленного репозитория:

git push --set-upstream origin new-branch

Команда предоставит вам выходные данные, чтобы вы знали о ходе работы, и это будет похоже на следующее:

Output
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 336 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To https://github.com/your-username/repository.git
   a1f29a6..79c0e80  new-branch  -> new-branch
Branch new-branch set up to track remote branch new-branch from origin.

Теперь вы можете перейти к разветвленному репозиторию на своей веб-странице GitHub и переключиться на ветку, которую вы нажали, чтобы увидеть изменения, внесенные вами в браузере.

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

Обновить локальный репозиторий

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

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

Настройка пульта для вилки

Удаленные репозитории позволяют вам сотрудничать с другими над проектом Git. Каждый удаленный репозиторий — это версия проекта, размещенная в Интернете или сети, к которой у вас есть доступ. Каждый удаленный репозиторий должен быть доступен вам либо только для чтения, либо для чтения и записи, в зависимости от ваших прав пользователя.

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

Давайте сначала проверим, какие удаленные серверы вы настроили. Команда git remote выведет список любого удаленного репозитория, который вы уже указали, поэтому, если вы клонировали свой репозиторий, как мы сделали выше, вы, по крайней мере, получите вывод относительно исходного репозитория, которому присвоено имя по умолчанию. Git для клонированного каталога.

Из каталога репозитория в нашем окне терминала давайте воспользуемся командой git remote вместе с флагом -v, чтобы отобразить URL-адреса, которые Git сохранил вместе с соответствующим удаленным короткие имена (как в «происхождении»):

git remote -v

Поскольку мы клонировали репозиторий, наш вывод должен быть примерно таким:

Output
origin    https://github.com/your-username/forked-repository.git (fetch)
origin    https://github.com/your-username/forked-repository.git (push)

Если вы ранее настроили более одного удаленного устройства, команда git remote -v предоставит список всех из них.

Далее мы укажем новый удаленный вышестоящий репозиторий для синхронизации с форком. Это будет оригинальный репозиторий, из которого мы разветвились. Мы сделаем это с помощью команды git remote add.

git remote add upstream https://github.com/original-owner-username/original-repository.git

Для нашего примера cloud_haiku эта команда будет следующей:

git remote add upstream https://github.com/do-community/cloud_haiku.git

В этом примере upstream — это короткое имя, которое мы указали для удаленного репозитория, поскольку с точки зрения Git «upstream» относится к репозиторию, из которого мы клонировали. Если мы хотим добавить удаленный указатель на хранилище соавтора, мы можем захотеть предоставить имя пользователя этого соавтора или сокращенный псевдоним для короткого имени.

Мы можем убедиться, что наш удаленный указатель на вышестоящий репозиторий был правильно добавлен, снова используя команду git remote -v из каталога репозитория:

git remote -v

Output
origin    https://github.com/your-username/forked-repository.git (fetch)
origin    https://github.com/your-username/forked-repository.git (push)
upstream    https://github.com/original-owner-username/original-repository.git (fetch)
upstream    https://github.com/original-owner-username/original-repository.git (push)

Теперь вы можете ссылаться на upstream в командной строке вместо того, чтобы писать весь URL-адрес, и вы готовы синхронизировать свой форк с исходным репозиторием.

Синхронизируйте вилку

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

Чтобы синхронизировать нашу ветку из каталога нашего локального репозитория в окне терминала, мы будем использовать команду git fetch для получения веток вместе с соответствующими фиксациями из вышестоящего репозитория. Поскольку мы использовали короткое имя «upstream» для ссылки на вышестоящий репозиторий, мы передадим его команде.

git fetch upstream

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

Output
From https://github.com/original-owner-username/original-repository
 * [new branch]      main     -> upstream/main

Теперь коммиты в основной ветке будут храниться в локальной ветке с именем upstream/main.

Перейдем к локальной основной ветке нашего репозитория:

git checkout main

Output
Switched to branch 'main'

Теперь мы объединим любые изменения, которые были сделаны в основной ветке исходного репозитория, доступ к которым мы будем получать через нашу локальную ветку upstream/main, с нашей локальной основной веткой:

git merge upstream/main

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

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

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

Создать запрос на слияние

На этом этапе вы готовы сделать запрос на включение в исходный репозиторий.

Вы должны перейти в свой разветвленный репозиторий и нажать кнопку New pull request в левой части страницы.

Вы можете изменить ветку на следующем экране. С любой стороны вы можете выбрать соответствующий репозиторий из выпадающего меню и соответствующую ветку.

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

Вы должны добавить заголовок и комментарий в соответствующие поля, а затем нажать кнопку «Создать запрос на включение».

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

Заключение

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

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

Если вы хотите узнать больше о Git и совместной работе над программным обеспечением с открытым исходным кодом, вы можете прочитать нашу серию руководств под названием Как использовать Git: справочное руководство».