Как изменить pull request

Практическое занятие «Процесс Pull request на GitHub»

На предыдущем занятии Используем клиент GitHub для десктопа, мы использовали Github Desktop для управления рабочим процессом коммитов, ветвления и слияния. На этом занятии мы будем выполнять аналогичные действия, но с использованием браузерного интерфейса, который предоставляет Github, вместо использования терминала или Github Desktop.

Понимание процесса Pull request является важным для анализа изменений в опен-сорс проекте с несколькими участниками. Использование интерфейса GitHub также удобно, если рецензенты не знакомы с терминалом или Github Desktop.

Создание изменение в отдельной ветке

По умолчанию в новом репозитории есть одна ветка с именем «Master». Обычно, когда при внесении изменений или просмотра / редактировании, создается новая ветка и вносятся все изменения в ветку. Затем, по окончании, владелец репо объединяет изменения из новой ветки в «Master» через «pull request».

Note: Можно выполнять эти операции, используя команды Git в терминале, а также Можно выполнять их в интерфейсе браузера. Интерфейс браузера может быть полезен, если людей, вносящих изменения в ваш контент.

Для создания изменений в отдельной ветке:

• Со стороны рецензента переходим к тому же репозиторию GitHub, который был создан на предыдущем занятии (можно создать новый репо). Создаем новую ветку, выбрав раскрывающееся меню ветки и введя имя новой ветки, например «sme-review». Затем нажмите клавишу Enter.

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

• Кликаем в область ввода текста, а затем кликаем по иконке карандаша («Edit this file»), чтобы отредактировать файл.

• Вносим изменения в контент и прокручиваем вниз экрана до области Commit changes. Поясняем причину изменений и подтверждаем изменения в своей ветке sme-review, нажав кнопку Commit changes .

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

Создание Pull request

Теперь представим, что процесс проверки завершен, и пришло время объединить ветку с мастером. Ветка объединяется с “Master” через Pull request . Любой «соавтор» в команде с правами на запись может инициировать и завершить Pull request (добавлять соавторов можете в «Настройки»> «Соавторы)

Для создания Pull request:

• Находим на экране вкладку “Pull request”.
• Кликаем по кнопке New pull request

• Выбираем ветку (sme-review), которую хотим сравнить с веткой “Master”

Когда мы сравниваем ветку с мастером, мы увидим список всех изменений. Мы можем просмотреть изменения в двух режимах просмотра: Unified или Split (это вкладки, показанные справа от содержимого). Unified показывает правки вместе в одной области содержимого, тогда как split показывает два файла рядом.

• Кликаем на кнопку Create pull request .
• Поясняем pull request и снова кликаем кнопку Create pull request .

Владелец репозитория увидит pull request и сможет принять меры для его объединения.

Процесс Pull request

Теперь посмотрим на процесс со стороны владельцем проекта, который получил новый Pull request. Владельцу нужно обработать Pull request и объединить ветку sme-review с “Master”.

• Переходим на вкладку “Pull requests”, чтобы увидеть ожидающие запросы на извлечение.
• Кликаем по запросу и смотрим изменения, выбрав вкладку Files changed.

Note: Для реализации выборочных изменений, переходим в ветку sme-review и вносим обновления перед обработкой pull request. Pull request не дает построчную информацию о том, какие изменения мы хотим принять или отклонить (например, в Microsoft Word «Отслеживать изменения»). Слияние запросов — это процесс «все или ничего». Можно нажать кнопку Review changes , добавить несколько комментариев, а затем установить переключатель «Request changes», попросив рецензента внести изменения.

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

• Переходим на вкладку “Conversation” и кликаем кнопку Merge pull request .
• кликаем Confirm merge .

Ветка sme-review объединяется с мастером. Теперь “Master” и ветка sme-review совпадают (ветки “смержены”).

• Кликаем кнопку Delete branch для удаления ветки sme-review.

Не обязательно удалять ветку сразу. Старые ветки всегда можете удалить , щелкнув ссылку на ветки при просмотре репозитория Github, а затем нажмите кнопку Delete (корзина) рядом с веткой.

Если посмотреть на список веток, то после удаления ветка sme-review больше не отображается.

Добавление участников в проект

Иногда необходимо добавлять соавторов в проект Github, чтобы они могли вносить изменения в ветку. Если другие участники проекта, не являясь соавторами, захотят внести изменения, они получат сообщение об ошибке. (Inviting collaborators to a personal repository)

Человек без прав на запись, может “форкнуть” (скопировать) репо, а не вносить изменения в ветку в том же проекте. Однако копирование проекта клонирует весь репозиторий, а не создает ветку в том же репозитории. Форк (копия) будет существовать в учетной записи пользователя GitHub. Можно объединить форкнутый репозиторий (это типичная модель для опен-сорс проектов со многими внешними участниками), но этот сценарий, вероятно, менее распространен для технических писателей, работающих с разработчиками в тех же проектах.

Для добавления соавторов в проект:

• В репозитории проекта переходи на вкладку “Settings”.
• Нажимаем на кнопку Collaborators в левой части.
• Вводим имена пользователей Github тех, кому хотим дать доступ в области Collaborator.
• Нажимаем на кнопку Add collaborator .

6.2 GitHub — Внесение собственного вклада в проекты

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

Создание ответвлений (fork)

Если вы хотите вносить свой вклад в уже существующие проекты, в которых у нас нет прав на внесения изменений путём отправки (push) изменений, вы можете создать своё собственное ответвление (fork) проекта. Это означает, что GitHub создаст вашу собственную копию проекта, данная копия будет находиться в вашем пространстве имён и вы сможете легко делать изменения путём отправки (push) изменений.

Примечание

Исторически так сложилось, что англоязычный термин «fork» (создание ветвления проекта) имел негативный контекстный смысл, данный термин означал, что кто-то повёл или ведёт проект с открытым исходным кодом в другом, отличном от оригинала, направлении, иногда данный термин так же означал создание конкурирующего проекта с раздельными авторами. В контексте GitHub, «fork» (создание ветвления проекта) просто означает создание ветвления проекта в собственном пространстве имён, что позволяет вносить публичные изменения и делать свой собственный вклад в более открытом виде.

Таким образом, проекты не обеспокоены тем, чтобы пользователи, которые хотели бы выступать в роли соавторов, имели право на внесение изменений путём их отправки (push). Люди просто могут создавать свои собственные ветвления (fork), вносить туда изменения, а затем отправлять свои внесённые изменения в оригинальный репозиторий проекта путём создания запроса на принятие изменений (Pull Request), сами же запросы на принятие изменений (Pull Request) будут описаны далее. Запрос на принятие изменений (Pull Request) откроет новую ветвь с обсуждением отправляемого кода, и автор оригинального проекта, а так же другие его участники, могут принимать участие в обсуждении предлагаемых изменений до тех пор, пока автор проекта не будет ими доволен, после чего автор проекта может добавить предлагаемые изменения в проект.

Для того, чтобы создать ответвление проекта, зайдите на страницу проекта и нажмите кнопку «Создать ответвление» («Fork»), которая расположена в правом верхнем углу.

Рисунок 88. Кнопка «Создать ответвление» («Fork»)

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

Рабочий процесс с использованием GitHub

GitHub разработан с прицелом на определённый рабочий процесс с использованием запросов на слияния. Этот рабочий процесс хорошо подходит всем: и маленьким, сплочённым вокруг одного репозитория, командам; и крупным распределённым компаниям, и группам незнакомцев, сотрудничающих над проектом с сотней копий. Рабочий процесс GitHub основан на тематических ветках, о которых мы говорили в главе Ветвление в Git.

Вот как это обычно работает:

1. Создайте форк проекта.
2. Создайте тематическую ветку на основании ветки master .
3. Создайте один или несколько коммитов с изменениями, улучшающих проект.
4. Отправьте эту ветку в ваш проект на GitHub.
5. Откройте запрос на слияние на GitHub.
6. Обсуждайте его, вносите изменения, если нужно.
7. Владелец проекта принимает решение о принятии изменений, либо об их отклонении.
8. Получите обновлённую ветку master и отправьте её в свой форк.

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

Давайте посмотрим, как можно предложить изменения в проект, размещённый на GitHub.

В большинстве случаев можно использовать официальный инструмент GitHub CLI вместо веб-интерфейса GitHub. Инструмент доступен в системах Windows, MacOS и Linux. Посетите страницу GitHub CLI homepage для получения инструкций по установке и использованию.

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

Тони ищет, чего бы запустить на своём новеньком Arduino. Кажется, он нашёл классный пример на https://github.com/schacon/blink.

Рисунок 89. Проект, над которым мы хотим поработать

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

Для начала, нажмите кнопку «Fork», как было сказано выше, чтобы заполучить собственную копию проекта. Мы зарегистрированы на GitHub под именем «tonychacon», так что наша копия окажется по адресу https://github.com/tonychacon/blink , где мы сможем редактировать её. Мы клонируем его, создадим тематическую ветку, внесём необходимые изменения и, наконец, отправим их на GitHub.

$ git clone https://github.com/tonychacon/blink (1) Cloning into 'blink'. $ cd blink $ git checkout -b slow-blink (2) Switched to a new branch 'slow-blink' $ sed -i '' 's/1000/3000/' blink.ino (macOS) (3) # If you're on a Linux system, do this instead: # $ sed -i 's/1000/3000/' blink.ino (3) $ git diff --word-diff (4) diff --git a/blink.ino b/blink.ino index 15b9911..a6cc5a5 100644 --- a/blink.ino +++ b/blink.ino @@ -18,7 +18,7 @@ void setup() < // the loop routine runs over and over again forever: void loop() < digitalWrite(led, HIGH); // turn the LED on (HIGH is the voltage level) [-delay(1000);-]// wait for a second digitalWrite(led, LOW); // turn the LED off by making the voltage LOW [-delay(1000);-] // wait for a second > $ git commit -a -m 'Change delay to 3 seconds' (5) [slow-blink 5ca509d] Change delay to 3 seconds 1 file changed, 2 insertions(+), 2 deletions(-) $ git push origin slow-blink (6) Username for 'https://github.com': tonychacon Password for 'https://tonychacon@github.com': Counting objects: 5, done. Delta compression using up to 8 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 340 bytes | 0 bytes/s, done. Total 3 (delta 1), reused 0 (delta 0) To https://github.com/tonychacon/blink * [new branch] slow-blink -> slow-blink

1. Клонируем нашу копию
2. Создаём тематическую ветку
3. Вносим свои изменения
4. Проверяем изменения
5. Фиксируем изменения в тематической ветку
6. Отправляем новую ветку в нашу копию на GitHub

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

Также можно зайти на страницу «Branches», по адресу https://github.com///branches , найти интересующую ветку и открыть запрос оттуда.

Рисунок 90. Кнопка открытия запроса на слияние

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

Также мы видим список коммитов в нашей тематической ветке, «опередивших» ветку master (в данном случае всего один коммит) и предпросмотр всех изменений, вносимых этими коммитами.

Рисунок 91. Страница создания запроса на слияние

После создания запроса на слияние (путём нажатия кнопки «Create pull request» на этой странице) владелец форкнутого проекта получит уведомление о предложенных изменениях со ссылкой на страницу с информацией о запросе.

Примечание

Запросы на слияние широко используются для публичных проектов типа описанного выше, когда участник уже подготовил все изменения для слияния с основным репозиторием. Тем не менее, часто можно встретить использование запросов на слияние во внутренних проектах в самом начале цикла разработки. Объяснение простое: вы можете обновлять тематическую ветку после открытия запроса на слияние, поэтому сам запрос открывается как можно раньше чтобы отслеживать прогресс разработки.

Обработка запроса на слияние

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

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

Рисунок 92. Комментирование определённой строки в запросе на слияние

Как только владелец прокомментирует изменения, автор запроса на слияние (а также все подписавшиеся на этот репозиторий) получат уведомления. Далее мы рассмотрим как настроить уведомления, но сейчас, если Тони включил уведомления через электронную почту, он получит следующее письмо:

Рисунок 93. Комментарии, отправленные по электронной почте

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

Рисунок 94. Страница обсуждения запроса на слияние

Теперь участник может видеть что ему необходимо сделать для того, чтобы его изменения были приняты. К счастью, это тоже легко сделать. Используя почту, вам потребуется заново отправить свои изменения в список рассылки, а при использовании GitHub вы просто делаете коммит в тематическую ветку и повторяете push, что автоматически обновляет запрос на слияние. На рисунке Финальная стадия запроса на слияние также видно, что в обновлённом запросе на слияние старый комментарий к коду был свёрнут, так как он относится к строке, которая с тех пор изменилась.

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

Рисунок 95. Финальная стадия запроса на слияние

Примечательно, что если вы перейдёте на вкладку «Files Changed» в этом запросе на слияние, то увидите «унифицированную» разницу — это суммарные изменения, которые будут включены в основную ветку при слиянии тематической ветки. В терминологии git diff это эквивалентно команде git diff master…​ для ветки, на которой основан этот запрос на слияние. В Определение применяемых изменений детальнее описан данный тип отличий.

GitHub так же проверяет может ли запрос на слияние быть применён без конфликтов и предоставляет кнопку для осуществления слияния на сервере. Эта кнопка отображается только если у вас есть права на запись в репозиторий и возможно простейшее слияние. По нажатию на неё GitHub произведёт «non-fast-forward» слияние, что значит даже если слияние может быть осуществлено перемоткой вперед, всё равно будет создан коммит слияния.

При желании, можно стянуть ветку и произвести слияние локально. Если эта ветка будет слита в master ветку и отправлена на сервер, то GitHub автоматически закроет запрос на слияние.

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

Примечание
Не только ответвления

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

Продвинутые запросы на слияние

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

Запросы слияния как Патчи

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

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

Например, если вы вернётесь и посмотрите на Финальная стадия запроса на слияние, то увидите, что участник не делал перебазирование своего коммита и не отправлял новый запрос на слияние. Вместо этого были сделаны новые коммиты и отправлены в существующую ветку. Таким образом, если вы в будущем вернётесь к этому запросу слияния, то легко найдёте весь контекст принятого решения. По нажатию кнопки «Merge» целенаправленно создаётся коммит слияния, который указывает на запрос слияния, оставляя возможность возврата к цепочке обсуждения.

Следование за исходным репозиторием

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

Рисунок 96. Запрос имеет конфликты слияния

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

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

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

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

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

$ git remote add upstream https://github.com/schacon/blink (1) $ git fetch upstream (2) remote: Counting objects: 3, done. remote: Compressing objects: 100% (3/3), done. Unpacking objects: 100% (3/3), done. remote: Total 3 (delta 0), reused 0 (delta 0) From https://github.com/schacon/blink * [new branch] master -> upstream/master $ git merge upstream/master (3) Auto-merging blink.ino CONFLICT (content): Merge conflict in blink.ino Automatic merge failed; fix conflicts and then commit the result. $ vim blink.ino (4) $ git add blink.ino $ git commit [slow-blink 3c8d735] Merge remote-tracking branch 'upstream/master' \ into slower-blink $ git push origin slow-blink (5) Counting objects: 6, done. Delta compression using up to 8 threads. Compressing objects: 100% (6/6), done. Writing objects: 100% (6/6), 682 bytes | 0 bytes/s, done. Total 6 (delta 2), reused 0 (delta 0) To https://github.com/tonychacon/blink ef4725c..3c8d735 slower-blink -> slow-blink

1. Добавляем исходный репозиторий как удалённый с именем upstream .
2. Получаем последние изменения из него.
3. Сливаем основную ветку в нашу тематическую.
4. Исправляем указанный конфликт.
5. Отправляем изменения в ту же тематическую ветку.

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

Рисунок 97. Запрос слияния без конфликтов

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

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

Ссылки

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

Давайте начнём с перекрёстных ссылок для запросов слияния или проблем. Всем запросам слияния и проблемам присваиваются уникальные номера в пределах проекта. Например, у вас не может быть запроса на слияние с номером #3 и проблемы с номером #3. Если вы хотите сослаться на любой запрос слияния или проблему из другого места, просто добавьте # в комментарий или описание. Так же можно указывать более конкретно, если проблема или запрос слияния находятся где-то ещё; пишите username# если ссылаетесь на проблему или запрос слияния, находящиеся в ответвлённом репозитории, или username/repo# если ссылаетесь на другой репозиторий.

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

Рисунок 98. Перекрёстные ссылки в запросе слияния

Когда мы отправим запрос на слияние, то увидим что-то вроде Отображение перекрёстных ссылок в запросе слияния.

Рисунок 99. Отображение перекрёстных ссылок в запросе слияния

Заметьте, что указанная полная ссылка на GitHub была сокращена до необходимого минимума.

Если Тони сейчас вернётся назад и закроет оригинальный запрос слияния, то мы это увидим, так как он упомянут в новом, а GitHub автоматически создаст отслеживающее событие в хронике запроса слияния. Это значит, что все, кто просматривает закрытый запрос слияния, могут легко перейти к запросу слияния, который его заменил. Ссылка будет выглядеть как указано на Отображение перекрёстных ссылок в закрытом запросе слияния.

Рисунок 100. Отображение перекрёстных ссылок в закрытом запросе слияния

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

GitHub-версия разметки Markdown

Ссылки на другие Проблемы — это лишь часть интереснейших вещей, которые вы можете делать в текстовых полях на GitHub. Для «проблемы» или «запроса слияния» в полях описания, комментария, комментария кода и других вы можете использовать так называемую «GitHub-версию разметки Markdown». Разметка похожа на обычный текст, который основательно преобразуется.

Смотрите Пример написания и отображения текста с разметкой для примера как использовать разметку при написании комментариев и текста.

Рисунок 101. Пример написания и отображения текста с разметкой

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

Списки задач

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

Список задач можно добавить следующим образом:

- [X] Write the code - [ ] Write all the tests - [ ] Document the code

Если добавить этот список в описание запроса на слияние или проблемы, то он будет отображён следующим образом Отображение списка задач в комментарии

Рисунок 102. Отображение списка задач в комментарии

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

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

Рисунок 103. Статистика задач в списке запросов слияния

Такая возможность невероятно полезна когда вы открываете запрос на слияние на раннем этапе реализации и отслеживаете прогресс с помощью него.

Отрывки кода

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

Для добавления отрывка кода следует обрамить его обратными кавычками.

```java for(int i=0 ; i < 5 ; i++) < System.out.println("i is : " + i); >```

Если вы укажете название языка, как показано на примере, GitHub попробует применить к нему подсветку синтаксиса. Для приведённого примера код будет выглядеть как на Отображение обрамлённого кода.

Рисунок 104. Отображение обрамлённого кода

Цитирование

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

Цитаты выглядят примерно так:

> Whether 'tis Nobler in the mind to suffer > The Slings and Arrows of outrageous Fortune, How big are these slings and in particular, these arrows?

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

Рисунок 105. Пример отображения цитаты

Смайлики

Наконец, вы можете использовать смайлики. На GitHub вы можете часто встретить их в комментариях или запросах на слияние. Для них есть даже помощник. Например, если при наборе комментария ввести символ двоеточия : , то будут предложены варианты автодополнения.

Рисунок 106. Автодополнение для смайлов в действии

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

I :eyes: that :bug: and I :cold_sweat:. :trophy: for :microscope: it. :+1: and :sparkles: on this :ship:, it's :fire::poop:! :clap::tada::panda_face:

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

Рисунок 107. Перегруженный смайликами комментарий

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

Примечание

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

Картинки

Технически, картинки не относятся к разметке GitHub, но их использование очень полезно. В дополнение к ссылкам на картинки в комментариях, GitHub позволяет встраивать картинки в комментарии.

Рисунок 108. Перетаскивание картинки для загрузки и встраивания

Если вернуться немного назад к Перекрёстные ссылки в запросе слияния, то над областью редактирования вы увидите небольшую подсказку «Parsed as Markdown». Нажав не неё, вы получите полную подсказку по использованию GitHub разметки.

Поддержание GitHub репозитория в актуальном состоянии

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

This branch is 5 commits behind progit:master.

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

Первый способ не требует конфигурации. Например, если вы сделали форк репозитория https://github.com/progit/progit2.git , то актуализировать ветку master можно следующим образом:

$ git checkout master (1) $ git pull https://github.com/progit/progit2.git (2) $ git push origin master (3)

1. Если вы находитесь на другой ветке — перейти на ветку master .
2. Получить изменения из репозитория https://github.com/progit/progit2.git и слить их с веткой master .
3. Отправить локальную ветку master в ваш форк origin .

Каждый раз писать URL репозитория для получения изменений достаточно утомительно. Этот процесс можно автоматизировать слегка изменив настройки:

$ git remote add progit https://github.com/progit/progit2.git (1) $ git fetch progit (2) $ git branch --set-upstream-to=progit/master master (3) $ git config --local remote.pushDefault origin (4)

1. Добавить исходный репозиторий как удалённый и назвать его progit .
2. Получить ветки репозитория progit , в частности ветку master .
3. Настроить локальную ветку master на получение изменений из репозитория progit .
4. Установить origin как репозиторий по умолчанию для отправки.

После этого, процесс обновления становится гораздо проще:

$ git checkout master (1) $ git pull (2) $ git push (3)

1. Если вы находитесь на другой ветке — перейти на ветку master .
2. Получить изменения из репозитория progit и слить их с веткой master .
3. Отправить локальную ветку master в ваш форк origin .

Данный подход не лишён недостатков. Git будет молча выполнять указанные действия и не предупредит вас в случае, когда вы добавили коммит в master , получили изменения из progit и отправили всё вместе в origin — все эти операции абсолютно корректны. Поэтому вам стоит исключить прямое добавление коммитов в ветку master , поскольку эта ветка фактически принадлежит другому репозиторию.

Перемещение и обновление pull-запросов

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

Требования

• Предварительно установленная система контроля версий Git. Подробные инструкции по установке можно найти здесь.
• Аккаунт и навыки работы в GitHub. Больше полезной информации можно найти в руководстве Создание pull-запроса на GitHub.

Перемещение кода и чистка комментариев

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

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

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

cd repository
git fetch upstream

После этого вы можете очистить комментарии, склеив или переименовав сообщение о коммите (возможно, этого делать не придётся, если вы не создавали множества маленьких коммитов).

Для начала нужно выполнить интерактивное перемещение. Этот процесс позволяет редактировать созданные ранее коммиты, объединять два или несколько коммитов в один, удалять и восстанавливать коммиты. Для этого нужно указать количество коммитов.

Чтобы узнать номера коммитов, созданных вами в этом проекте, введите команду:

Команда вернёт такой результат:

commit 46f196203a16b448bf86e0473246eda1d46d1273
Author: username-2
Date: Mon Dec 14 07:32:45 2015 -0400
Commit details
commit 66e506853b0366c87f4834bb6b39d941cd034fe3
Author: username1
Date: Fri Nov 27 20:24:45 2015 -0500
Commit details

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

git log —author=your-username

Если же вы разрабатываете несколько веток, используйте параметр –branches[=], чтобы выполнить поиск коммитов по веткам.

Зная количество коммитов, вы можете выполнить перемещение с помощью команды:

git rebase -i HEAD~x

• Параметр –i запускает интерактивное перемещение;
• HEAD ссылается на последний коммит ветки master;
• x – количество коммитов, сделанных вами с начала работы над веткой.

Если же вы не знаете, сколько коммитов вы сделали в ветке, вам нужно узнать, на каких коммитах основана ветка. Для этого используйте:

git merge-base new-branch master

Эта команда вернёт длинную строку – хэш коммита. Он выглядит примерно так:

Вы можете использовать этот хэш в команде:

git rebase -i 66e506853b0366c87f4834bb6b39d341cd094fe9

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

Объединение коммитов

Команда squash позволяет объединить два (и больше) маленьких коммита в один большой.

Перед каждым коммитом в файле вы увидите слово pick:

pick a1f29a6 Adding a new feature
pick 79c0e80 Here is another new feature
# Rebase 66e5068..79c0e80 onto 66e5068 (2 command(s))

Теперь везде, кроме первой строки, слово pick нужно заменить словом squash, чтобы объединить коммиты:

pick a1f29a6 Adding a new feature
squash 79c0e80 Here is another new feature

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

Successfully rebased and updated refs/heads/new-branch.

Переименование коммита

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

После интерактивного перемещения у вас будет открытый файл, который выглядит так:

pick a1f29a6 Adding a new feature
pick 79c0e80 Here is another new feature
# Rebase 66e5068..79c0e80 onto 66e5068 (2 command(s))

Перед каждым коммитом, который вы хотите переписать, замените pick словом reword:

pick a1f29a6 Adding a new feature
reword 79c0e80 Adding a second new feature
# Rebase 66e5068..79c0e80 onto 66e5068 (2 command(s))

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

Завершение перемещения

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

git rebase upstream/master

После этого Git перенесёт все коммиты на последнюю версию ветки master. Если при этом произошёл конфликт, Git предложит вам несколько вариантов его решения. Выберите один из предложенных вариантов и введите:

git rebase —continue

После этого Git завершит перемещение.

Обновление pull-запроса

После перемещения история ветки будет переписана, и вы больше не сможете использовать команду git push, потому что путь изменится.

Чтобы загрузить изменённую ветку, используйте флаг –force или –f. Так вы сможете сообщить Git о том, что вы знаете обо всех загружаемых изменениях.

Установите значение simple в push.default (по умолчанию в Git 2.0+).

git config —global push.default simple

Убедитесь, что вы работаете на правильной ветке:

git checkout new-branch
Already on ‘new-branch’
. . .

После этого можно запустить force-push:

Эта команда обновит pull-запрос.

Восстановление утраченных коммитов

Если вы случайно потеряли нужный вам коммит, Git может восстановить его.

Для этого существует команда git reflog, которая находит утраченный коммит и создаёт из него новую ветку.

Reflog – это сокращение от reference logs, так называются логи, которые фиксируют изменения в локальном репозитории.

В локальном репозитории нужно запустить:

46f1962 HEAD@: checkout: moving from branch-1 to new-branch
9370d03 HEAD@: commit: code cleanups
a1f29a6 HEAD@: commit: brand new feature
38f2fc2 HEAD@: commit: remove testing methods
. . .

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

С помощью этой информации вы можете восстановить коммит.

git checkout -b new-new-branch a1f29a6

Эта команда создаст новую ветку на основе третьего коммита.

После этого вы можете создать новый pull-запрос или же снова переместить ветку.

Примечание: Если вы недавно запускали команду git gc, чтобы удалить ненужные файлы и оптимизировать локальный репозиторий, вероятно, вы не сможете восстановить утраченные коммиты.

Проверка кода

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

В зависимости от проекта, запрос может оставаться на рассмотрении в течение некоторого времени. Возможно, владелец проекта предложит вам поработать над вашим pull-запросом, изменить его.

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

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

Очень важно, чтобы ваши коммиты отвечали всем требованиям проекта.

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

Удаление ветки

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

Об этом уже говорилось в предыдущем руководстве (в разделе о синхронизации).

Для этого введите:

git checkout master
git pull —rebase upstream master
git push -f origin master

Теперь нужно очистить локальную и удалённую ветку. Чтобы удалить локальную ветку, введите:

git branch -d new-branch

Флаг –d удаляет указанную в команде ветку.

Примечание: Вместо new-branch нужно ввести название своей ветки.

Чтобы удалить удалённую ветку, введите:

git push origin —delete new-branch

Теперь все разработанные вами изменения находятся только в главном репозитории проекта.

Заключение

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

Создание запроса на включение изменений

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

Кто может использовать эту функцию.

Anyone with read access to a repository can create a pull request.

Platform navigation

Tool navigation

If you want to create a new branch for your pull request and do not have write permissions to the repository, you can fork the repository first. For more information, see «Creating a pull request from a fork» and «About forks.»

You can specify which branch you’d like to merge your changes into when you create your pull request. Pull requests can only be opened between two branches that are different.

Note: To open a pull request in a public repository, you must have write access to the head or the source branch or, for organization-owned repositories, you must be a member of the organization that owns the repository to open a pull request.

You can link a pull request to an issue to show that a fix is in progress and to automatically close the issue when someone merges the pull request. For more information, see «Linking a pull request to an issue.»

Changing the branch range and destination repository

By default, pull requests are based on the parent repository’s default branch. For more information, see «About branches.»

If the default parent repository isn’t correct, you can change both the parent repository and the branch with the drop-down lists. You can also swap your head and base branches with the drop-down lists to establish diffs between reference points. References here must be branch names in your GitHub repository.

When thinking about branches, remember that the base branch is where changes should be applied, the head branch contains what you would like to be applied.

When you change the base repository, you also change notifications for the pull request. Everyone that can push to the base repository will receive an email notification and see the new pull request in their dashboard the next time they sign in.

When you change any of the information in the branch range, the Commit and Files changed preview areas will update to show your new range.

Tips:

• Using the compare view, you can set up comparisons across any timeframe. For more information, see «Comparing commits.»
• Project maintainers can add a pull request template for a repository. Templates include prompts for information in the body of a pull request. For more information, see «About issue and pull request templates.»

Creating the pull request

1. On GitHub.com, navigate to the main page of the repository.
2. In the «Branch» menu, choose the branch that contains your commits.

Above the list of files, in the yellow banner, click Compare & pull request to create a pull request for the associated branch.

Tip: After you create a pull request, you can ask a specific person to review your proposed changes. For more information, see «Requesting a pull request review.»

After your pull request has been reviewed, it can be merged into the repository.

To learn more about GitHub CLI, see «About GitHub CLI.»

To create a pull request, use the gh pr create subcommand.

gh pr create 

To assign a pull request to an individual, use the —assignee or -a flags. You can use @me to self-assign the pull request.

gh pr create --assignee "@octocat" 

To specify the branch into which you want the pull request merged, use the —base or -B flags. To specify the branch that contains commits for your pull request, use the —head or -H flags.

gh pr create --base my-base-branch --head my-changed-branch 

To include a title and body for the new pull request, use the —title and —body flags.

gh pr create --title "The bug is fixed" --body "Everything works again" 

To mark a pull request as a draft, use the —draft flag.

gh pr create --draft 

To add a labels or milestones to the new pull request, use the —label and —milestone flags.

gh pr create --label "bug,help wanted" --milestone octocat-milestone 

To add the new pull request to a specific project, use the —project flag.

gh pr create --project octocat-project 

To assign an individual or team as reviewers, use the —reviewer flag.

gh pr create --reviewer monalisa,hubot --reviewer myorg/team-name 

To create the pull request in your default web browser, use the —web flag.

gh pr create --web 

1. Click Preview Pull Request. GitHub Desktop will open a preview dialog showing the diff of the changes between your current branch and the base branch.

Alternatively, to go straight to GitHub to create your pull request, select the dropdown icon and click Create Pull Request.
Confirm that the branch in the base: dropdown menu is the branch where you want to merge your changes.

GitHub Desktop will advise you whether the current branch can be automatically merged into the base branch.

1. Once you’ve committed changes to your local copy of the repository, click the Create Pull Request icon.

Check that the local branch and repository you’re merging from, and the remote branch and repository you’re merging into, are correct. Then give the pull request a title and a description.

For more information on creating pull requests in GitHub Codespaces, see «Using GitHub Codespaces for pull requests.»

Further reading

• «Creating a pull request from a fork»
• «Keeping your pull request in sync with the base branch»
• «Changing the base branch of a pull request»
• «Adding issues and pull requests to a project (classic)»
• «Creating an issue»
• «Assigning issues and pull requests to other GitHub users»
• «Writing on GitHub»