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

Введение

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

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

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

Предпосылки

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

Вам также потребуется иметь или создать учётную запись GitHub. Это можно сделать на сайте GitHub (github.com), войдя в систему или создав учётную запись.

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

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

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

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

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

Форк репозитория

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

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

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

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

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

https://github.com/username/repository

Или вы можете найти проект, используя строку поиска GitHub.

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

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

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

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

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

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

Имитация репозитория

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

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

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

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

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

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

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

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

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

Начальная ветвь репозитория проекта обычно называется главной ветвью (master). Рекомендуется рассматривать все компоненты главной ветви как готовые к развертыванию, чтобы другие могли использовать их в любое время.

Примечание: В июне 2020 года GitHub обновил свою терминологию, чтобы называть ветки исходного кода по умолчанию «главными» (master branchs), а не «главными» (master branchs). Если ваша ветка по умолчанию всё ещё отображается как «главная» (master), вы можете изменить её на «главную» (master), изменив настройки ветки по умолчанию.

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

Чтобы создать ветку из окна терминала, мы меняем наш рабочий каталог на каталог репозитория. Для перехода в этот каталог обязательно используйте фактическое имя репозитория (например, 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

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

git checkout main

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

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

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

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

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 может выглядеть примерно так:.

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"

или vim:

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 сохранил вместе с их соответствующими короткими удаленными именами (например, “origin”):

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. Поскольку мы использовали короткое имя “upstream” для обозначения репозитория 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, в нашу локальную ветку master:

git merge upstream/main

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

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

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

Запрос на извлечение

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

Вам нужно перейти в репозиторий вашего форка и нажать кнопку нового запроса на извлечение в левой части экрана.

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

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

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

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

Результат

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

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