Pool request что это

Выполнение запроса pull

Pull requests are a feature that makes it easier for developers to collaborate using Bitbucket. They provide a user-friendly web interface for discussing proposed changes before integrating them into the official project.

В упрощенном виде запросы pull — это механизм, с помощью которого разработчик уведомляет участников команды о том, что он подготовил некий функционал. Закончив работу над функциональной веткой, разработчик создает запрос pull с помощью аккаунта Bitbucket. Так все участники процесса узнают, что требуется проверить код и выполнить слияние с главной веткой ( main ).

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

По сравнению с другими моделями совместной работы это формальное решение для обмена коммитами обеспечивает гораздо более упорядоченный рабочий процесс. SVN и Git могут автоматически отправлять уведомления по электронной почте с помощью простого скрипта; однако когда дело доходит до обсуждения изменений, разработчикам обычно приходится вести диалог по электронной почте. Такой подход может внести путаницу, особенно если начинается обмен дополняющими коммитами. Запросы pull помещают все эти функции в удобный веб-интерфейс рядом с репозиториями Bitbucket.

Структура запроса pull

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

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

Порядок действий

Пул-реквесты можно применять в сочетании с процессами Feature Branch Workflow, Gitflow Workflow или Forking Workflow. При этом для использования пул-реквестов требуются две отдельные ветки или два отдельных репозитория. Поэтому пул-реквесты не будут работать при использовании процесса Centralized Workflow. Использование пул-реквестов в каждом из перечисленных процессов имеет свои нюансы, но общий подход описан ниже.

1. Разработчик создает функцию в отдельной ветке в своем локальном репозитории.

2. The developer pushes the branch to a public Bitbucket repository.

3. The developer files a pull request via Bitbucket.

4. The rest of the team reviews the code, discusses it, and alters it.

5. The project maintainer merges the feature into the official repository and closes the pull request.

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

Связанные материалы

Расширенный журнал Git

СМ. РЕШЕНИЕ

Изучите Git с помощью Bitbucket Cloud

Использование запросов pull в рабочем процессе с функциональными ветками

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

В процессе Feature Branch существует только один публичный репозиторий, поэтому исходный и целевой репозитории в запросе pull всегда будут совпадать. Обычно разработчик указывает свою функциональную ветку в качестве исходной, а ветку main — в качестве целевой ветки.

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

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

Использование запросов pull в рабочем процессе Gitflow

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

Механизм запросов pull в рабочем процессе Gitflow аналогичен описанному выше: разработчик просто создает запрос pull, когда необходимо проверить функцию, релиз или ветку исправлений, а остальные участники команды получают уведомления через Bitbucket.

Слияние функциональных веток обычно выполняют с веткой разработки develop , а слияние веток релизов и исправлений выполняют и с веткой develop , и с веткой main . Запросы pull можно использовать в качестве инструмента формального управления всеми этими слияниями.

Использование запросов pull в рабочем процессе с форками

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

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

Поскольку у каждого разработчика есть свой публичный репозиторий, исходный и целевой репозитории в запросе pull будут отличаться. Исходным будет публичный репозиторий разработчика, а исходной веткой — та, что содержит предлагаемые изменения. Если разработчик предлагает слить функциональную ветку с основной базой кода, целевым репозиторием будет официальный репозиторий проекта, а целевой веткой — главная ветка main .

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

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

Пример

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

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

Мэри создает форк официального проекта

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

Указав имя и описание для репозитория, создаваемого с помощью форка, она получит копию серверной части проекта.

Мэри клонирует свой репозиторий Bitbucket

Затем Мэри должна клонировать репозиторий Bitbucket, который она только что создала с помощью форка. Так она получит собственную рабочую копию проекта на своей локальной машине. Она может сделать это с помощью следующей команды:

git clone https://user@bitbucket.org/user/repo.git

Помните, что команда git clone автоматически создает удаленный репозиторий origin , который указывает на репозиторий Мэри, созданный с помощью форка.

Мэри разрабатывает новый функционал

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

git checkout -b some-feature
# Edit some code
git commit -a -m "Add first draft of some feature"

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

Мэри помещает функциональную ветку в свой репозиторий Bitbucket

Закончив свою задачу, Мэри помещает функциональную ветку в собственный репозиторий Bitbucket (не в официальный репозиторий проекта) с помощью простой команды git push :

git push origin some-branch

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

Мэри создает запрос pull

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

Мэри хочет выполнить слияние функциональной ветки с основной базой кода. При этом исходной веткой будет ее функциональная ветка, целевым репозиторием — публичный репозиторий Джона, а целевой веткой — ветка main . Мэри потребуется ввести заголовок и описание запроса pull. Если кто-либо еще кроме Джона должен одобрить код Мэри, она может указать нужных людей в поле Reviewers (Проверяющие).

После создания запроса pull Джону будет отправлено уведомление через Bitbucket и (опционально) по электронной почте.

Джон просматривает запрос pull

Джон может увидеть все созданные другими разработчиками пул-реквесты, перейдя на вкладку Pull request в своем репозитории Bitbucket. Нажав на пул-реквест Мэри, он увидит описание пул-реквеста, историю коммитов функциональной ветки и все изменения в пул-реквесте.

Если Джон считает функционал готовым к слиянию с проектом, ему достаточно нажать кнопку Merge (Слияние), чтобы одобрить запрос pull и выполнить слияние функционала Мэри со своей веткой main .

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

Мэри добавляет дополняющий коммит

Если у Мэри есть какие-либо вопросы по поводу отзыва Джона, она может ответить внутри запроса pull, используя его как форум для обсуждения функции.

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

Джон принимает запрос pull

В конечном счете Джон принимает изменения, выполняет слияние функциональной ветки с главной и закрывает запрос pull. Функциональная ветка включена в проект. И теперь каждый разработчик проекта может скопировать изменения в свой локальный репозиторий, выполнив стандартную команду git pull .

Куда можно перейти отсюда

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

Что такое pull request?

@Pavel Mayorov, на официальном сайте GitHub — который, на мой взгляд, является наиболее авторитетным источником насчёт именования термина, — термин «pull request» пишется строчными буквами, примеры: About pull requests, Merging a pull request, Reverting a pull request. Спасибо.

4 янв 2017 в 8:49

@СашаЧерных он там по-разному пишется. Перейдите по той ссылке, которую вы приводили первый раз и посмотрите в самый низ

4 янв 2017 в 8:53

4 ответа 4

Сортировка: Сброс на вариант по умолчанию

Смотрим за руками.

1. Крутой программер создал репозиторий.
2. Вы сделали форк его репозитория (т.е. скопировали к себе).
3. Вы сделали какие-то крутые изменения в своём репозитории.

Теперь если вы хотите, чтобы крутой дядя внёс ваши крутые изменения в свой крутой код. И вы просите, чтобы он взял ваши изменения, т.е. сделал git pull . Это и называется pull request

Отслеживать
28.5k 12 12 золотых знаков 58 58 серебряных знаков 118 118 бронзовых знаков
ответ дан 10 авг 2012 в 13:18
Dmitry Manannikov Dmitry Manannikov
1,675 1 1 золотой знак 9 9 серебряных знаков 9 9 бронзовых знаков
А как теперь этот пулл реквест применить к своему репозиторию?))
11 авг 2012 в 9:26
Нажать «Accept Pull Request», не?
11 авг 2012 в 9:43

Что значит применить? Вы просите кого то (нажав кнопку на гитхабе) влить ВАШИ изменения в ЕГО репозиторий. Влить или не вливать — его дело.

11 авг 2012 в 9:43

Почему «крутой», «крутые»? Я мелочи, в основном, делаю. Исправляю небольшие баги, изменяю формат даты, добавляю улучшения в юзабилити и т. д. Самое смешное: пофиксишь опечатку — GitHub тебя уже в контрибуторы зачисляет. Спасибо.

28 сен 2016 в 3:31
git pull тут ни при чём. При принятии реквеста git merge делается.
12 дек 2016 в 7:57

К вышесказанному можно добавить следующее. Далеко не все пулл-реквесты принимаются разработчиками. Тут нужно соблюсти ряд правил:

1. Пулл-реквест (ПР) должен быть хорошо оформлен и содержать исчерпывающее описание.
2. Обычное правило, один баг — один ПР, одна фича — один ПР. Не нужно пытаться впихнуть сразу кучу всего.
3. Очень важно соблюдать Code Style того проекта, для которого вы делаете ПР. Пусть даже он кажется вам противоестественным (например вы всегда делаете отступы в виде 4 пробелов, а в проекте табы).

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

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

Отслеживать
ответ дан 17 сен 2015 в 18:50
3,324 1 1 золотой знак 15 15 серебряных знаков 32 32 бронзовых знака

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

еще добавки к вышесказанному: возможный (я им пользуюсь) механизм работы с репами/pr:

git clone https://github.com/ваш_юзернейм/sqlpp11.git

git remote add upstream https://github.com/rbock/sqlpp11.git (т.е. мы добавляем псевдоним upstream для оригинального репозитория, мы не можем добавлять в него изменения, но можем их получать)

git checkout -b названиеБранча (ветки)

теперь вы правите файлы в вашем origin, в вашей ветке, пушите их в свой форк гитхаба (origin), откуда и делаете pull-request

при этом вы можете сделать git merge/pull/fetch upstream с оригинального репозитория (upstream)

если в upstream настроена интеграция типа travis-ci (как в моем примере), лучше не делать пулл-реквесты, пока не настроите travis-ci для своего репозитория и ваши билды не будут работать правильно (чтобы не мучать мэйнтейнера upstream бессмысленными сообщениями о неудачных сборках в пулл-реквесте)

общий алгоритм работы примерно такой: git fetch; git merge upstream/ветка; (master/debug/и т.д.) сделали изменения: git push , изменения улетают в ваш форк на гитахабе. Eсли настроен travis, проходят тесты/сборки, когда вы уверены в качестве коммита, делаете pull request из вашего форка. Если PR приняли, делаете, допустим, git checkout master; git fetch; git merge upstream/ветка , чтобы ваш форк оставался консистентным с оригиналом.

вмердженные в upstream (оригиальный репозиторй) и в ваш origin/master (ваш форк на гитхабе, в данном случае) ветки можно удалять — руками или с помощью, например, https://github.com/arc90/git-sweep

Отслеживать
ответ дан 17 июн 2016 в 21:12
strangeqargo strangeqargo
5,754 20 20 серебряных знаков 32 32 бронзовых знака

1. Что такое pull request?

1. Определение

pull request — предложение изменения кода в чужом репозитории.

Вы делаете форк чужого репозитория (который иногда и сам может быть форком) → производите изменения в своём форке → посредством pull request предлагаете изменения владельцам репозитория, чей форк Вы сделали. На GitHub pull request в публичный репозиторий может осуществить любая/ой зарегистрированная/ый участница/участник.

2. Составляющие pull requests

1. Изменения, которые собираетесь внести в чужой репозиторий,
2. Описание этих изменений.

Рекомендации по грамотному внесению pull requests расписаны в ответе ув-мого IonDen.

3. Разновидности pull requests

Все pull requests можно разделить на следующие категории:

1. Исправление багов, ошибок, конфликтов с другими приложениями,
2. Добавление новых функций, возможностей,
3. Рефакторинг, стилевые правки. Если владелица/владелец репозитория не значительно хуже Вас разбирается в коде репозитория, лучше не злоупотреблять pull requests данной категории.

4. Дополнительная ссылка

2. Как сделать и принять pull request при помощи hub

1. Что такое hub?

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

git clone https://github.com/Kristinita/SashaSublime.git 

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

hub clone Kristinita/SashaSublime 

Полный список команд hub, и что они упрощают, см. в документации hub.

На момент написания ответа (ноябрь 2016) hub работает только с GitHub, но не BitBucket или прочими ресурсами для хранения кода. Для пользователей Windows доступна установка через пакетный менеджер Chocolatey — cinst hub -y .

2. Зачем использовать hub?

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

• IDE/продвинутые текстовые редакторы предоставляют значительно больше возможностей для работы с кодом в сравнении с редактированием в вебе;
• Могут понадобиться разного рода тесты, недоступные при редактировании в веб-интерфейсе;
• Для многих предпочтительнее работать в терминале.

Итак, вы решили клонировать репозиторий. hub упрощает:

• Клонирование удалённого репозитория; рассмотрено в п. 2.1 данного ответа;
• Форк; достаточно ввести в терминал hub fork ;
• pull request; после того, как Вы запушили изменения в свой форк, достаточно ввести в терминал hub pull-request .

3. Настройка hub перед использованием

1. Создайте пользовательскую переменную среды GIT_EDITOR , — это сделать просто при помощи Rapid Environment Editor, — значением для которой будет путь к исполняемому файлу Вашего редактора, в котором Вам удобно писать pull request message, — описание Вашего pull request, — при необходимости добавив аргументы командной строки. Например, у меня для Sublime Text значение вышло следующим:

"D:\Sublime Text 3 x64\sublime_text.exe" -n -w 

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

1. При использовании hub в Windows и открытии редактируемых файлов в Sublime Text могут возникнуть проблемы с pull requests от имени администратора. Поскольку это не первая моя проблема, связанная с UAC, а толку от него не вижу, я отключил у себя контроль учётных записей.
2. Комментарии — текст под сообщением во вкладке PULLREQ_EDITMSG — по умолчанию выделяются #октоторпами# . Но когда Вы внесёте pull request в чужой репозиторий, то обнаружите, что текст под сообщением отобразится как заголовки, а не комментарии.

git config --global core.commentChar % 

Отныне комментариям во вкладке PULLREQ_EDITMSG будут предшествовать символы %процента% , после внесения pull request комментариев не будет видно как визуально, так и в исходном коде описания к pull request.

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

git config --list --show-origin 

Например, у меня в Windows 10 путь к файлу, где хранится данная настройка для комментариев, оказался следующим:

file:C:/Users/SashaChernykh/.gitconfig core.commentchar=% 

Если Ваша проблема отлична от расписанных здесь, и её разрешения не получается найти поисками Google и по репозиторию; попробуйте ещё раз воспроизвести проблему, перед введением команд hub послав в терминал следующую команду:

set HUB_VERBOSE=1 

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

4. Пример создания pull request через hub

Сделаем посредством PowerShell и hub pull request в репозиторий https://github.com/LightAlf/bioRepo1. Помимо вышеперечисленных команд hub в примере используются также команды git, о предназначении которых можно узнать, например, из данного или этого ресурсов на русском.

PS E:\> hub clone LightAlf/bioRepo1 Cloning into 'bioRepo1'. remote: Counting objects: 16, done. remote: Total 16 (delta 0), reused 0 (delta 0), pack-reused 16 Unpacking objects: 100% (16/16), done. PS E:\> cd bioRepo1 PS E:\bioRepo1> Invoke-Item README.MD # В Вашем редакторе открывается файл README.MD → вносите в него изменения → сохраняете файл. PS E:\bioRepo1> git add . PS E:\bioRepo1> git commit -m "Тестирование pull-request посредством hub" [master 839c146] Тестирование pull-request посредством hub 1 file changed, 2 insertions(+) PS E:\bioRepo1> hub fork Updating Kristinita From https://github.com/LightAlf/bioRepo1 * [new branch] discuss -> Kristinita/discuss * [new branch] master -> Kristinita/master new remote: Kristinita PS E:\bioRepo1> git checkout -b SashaGoddess Switched to a new branch 'SashaGoddess' PS E:\bioRepo1> git push Kristinita SashaGoddess Counting objects: 3, done. Delta compression using up to 4 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 471 bytes | 0 bytes/s, done. Total 3 (delta 0), reused 0 (delta 0) To https://github.com/Kristinita/bioRepo1.git * [new branch] SashaGoddess -> SashaGoddess PS E:\bioRepo1> hub pull-request # Откроется вкладка с файлом PULLREQ_EDITMSG, как на картинке ниже → вписываете в него изменения → сохраняете файл → закрываете его. https://github.com/LightAlf/bioRepo1/pull/2 PS E:\bioRepo1> 

5. Пример принятия pull-request при помощи hub

Если pull request предложен Вам, Вы можете принять его из терминала, воспользовавшись командой hub — hub merge . Изменения будут влиты в Ваш локальный репозиторий; чтобы перенести их на удалённый, следует сделать git push . Пример, как принять pull-request. если ветка, в которую предложили сделать pull request, является веткой по умолчанию.

SashaChernykh@DESKTOP-0G54NVG MINGW32 /e/SashaChocolatey (master) # Где E:\SashaChocolatey — локальный репозиторий, в связанный с которым удалённый репозиторий был внесён pull-request $ hub merge https://github.com/Kristinita/SashaChocolatey/pull/1 # Где https://github.com/Kristinita/SashaChocolatey/pull/1 — ссылка на pull-request Merge made by the 'recursive' strategy. packages/Karens Replicator/tools/chocolateyinstall.ps1 | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) SashaChernykh@DESKTOP-0G54NVG MINGW32 /e/SashaChocolatey (master) $ hub push Counting objects: 15, done. Delta compression using up to 4 threads. Compressing objects: 100% (13/13), done. Writing objects: 100% (15/15), 1.56 KiB | 0 bytes/s, done. Total 15 (delta 8), reused 0 (delta 0) remote: Resolving deltas: 100% (8/8), completed with 3 local objects. To https://github.com/Kristinita/SashaChocolatey.git 79ebe12..5045130 master -> master 

В описании коммита по умолчанию будут ссылки на коммит, которым приниматеся pull request, и на сам pull request, а также его заголовок.

Пользовательница/пользователь GitHub, у которой/которого Вы приняли pull request, не сразу, но будет указана/указан в числе контрибьюторов Вашего репозитория.

3. Дополнительная ссылка

Как сделать свой первый Pull Request

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

Сначала мы приведём высокоуровневое описание процесса , а затем подробно опишем каждый этап.

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

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

Вот процесс с высоты птичьего полёта.

1. Форкните проект.
2. Склонируйте репозиторий.
3. Создайте ветку для своей работы.
4. Сделайте необходимые изменения в файлах — коде , документации , тестах. Закоммитьте их в только что созданную ветку.
5. Убедитесь , что проект работает после ваших изменений.
6. Сделайте Pull Request.
7. Обсудите его с рецензентом в процессе Code Review. При необходимости , внесите изменения в свой Pull Request.
8. Когда все довольны , Pull Request принимают — с этого момента ваши изменения попали в исходный репозиторий ( upstream) и являются частью проекта.

Работа над задачей закончена!

Теперь рассмотрим каждый этап подробнее.

Форкаем проект

Вы не можете отправлять коммиты ( git push ) напрямую в исходный репозиторий. По желанию хозяин проекта может это разрешить , но обычно доступ на запись есть только у людей , поддерживающих проект , а все остальные работают через Pull Request’ы ( «запросы на вливание изменений»; о них — ниже).

Поэтому мы форкаем проект — это создаст копию репозитория в вашем аккаунте. При этом у вас появится доступ на запись в вашу копию.

Через мгновение вы будете перенаправлены на страницу вашего форка.

Клонируем репозиторий

Затем нужно склонировать репозиторий на вашу локальную машину. Для этого нам нужен URL репозитория. Нажав на кнопку справа , вы скопируете его в буфер обмена. Обратите внимание на выбранный слева протокол. Если вы не настраивали SSH для GitHub, там должно быть указано HTTPS .

Затем выполняем команду в терминале ( или командной строке Windows):

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

Создаём ветку

Ветка по умолчанию — master . Чтобы изменениями было проще управлять и они не смешивались друг с другом , создадим отдельную ветку , где и будем работать. При этом ветку стоит назвать так , чтобы имя говорило о её назначении.

Например , мы хотим исправить ошибку в реализации протокола PROTOBAZ , так что наша ветка будет называться fix-protobaz .

Теперь заходим в наш склонированный репозиторий и создаём ветку:

cd foobar git checkout -b fix-protobaz

Вторая команда создаст ветку и перейдёт на неё ( сделает checkout).

Если после этого выполнить git status , он покажет

On branch fix-protobaz nothing to commit, working directory clean

Эту команду стоит запомнить — когда не понимаете , в каком состоянии репозиторий, просто выполните её. Чаще всего в её выводе git покажет другие команды, которые делают то , что вы ( скорее всего) и хотите сделать.

Делаем изменения

Теперь приступаем к работе. Редактируем код , обновляем документацию , чиним тесты , дополняем README.

Эти изменения мы коммитим в нашу ветку. Как это сделать — ниже.

При этом старайтесь делать коммиты часто , а сами коммиты — небольшими по объёму. Каждый коммит должен делать ровно одну вещь , и при этом поддерживать работоспособность проекта. Стремиться нужно к тому , чтобы в будущем можно было перейти на любой коммит и получить рабочий проект.

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

Если вы уже достаточно разбираетесь в Git, такие не-атомарные изменения потом нужно объединить в один коммит с помощью interactive rebase и squash.

Итак , после редактирования файлов мы имеем следующую ситуацию ( это вывод git status ):

1 2 3 4 5 6 7 8

On branch fix-protobaz Changes not staged for commit: (use "git add . " to update what will be committed) (use "git checkout -- . " to discard changes in working directory) modified: src/protobaz.rs no changes added to commit (use "git add" and/or "git commit -a")

В выводе есть все необходимые вам команды:

• git add . добавляет файл в содержимое коммита , который вы собираетесь записать
• git checkout — . откатывает ваши изменения файла

Поэтому делаем git add src/protobaz.rs , а затем git commit . Откроется редактор , в котором нужно ввести сообщение коммита.

Сообщение коммита — это описание того , что вы сделали. Его читают другие участники проекта и рецензент. Поэтому оно должно быть осмысленным и читаемым.

Формат сообщения о коммите таков:

1 2 3 4 5 6

Краткое описание коммита (не более 50 символов) Подробное описание коммита - зачем он сделан, почему нельзя сделать по-другому, источники информации. Служебная информация - теги, ссылки на задачи, какие задачи коммит закрывает.

1 2 3 4 5 6 7 8

Исправляем длину буфера в реализации PROTOBAZ Неверное вычисление длины приводило к отсечению части сообщения в ситуации, когда пользователь использует foobar-1.3.4. Смотри http://foobar.org/bugs?id=1234 Fix #123

Из всех частей сообщения , только первая является обязательной.

Она должна иметь вид . Говорим о том , что мы делаем в этом коммите: [мы] исправляем ошибку , [мы] добавляем возможность , [мы] обновляем документацию.

Последняя строка — это команда GitHub. Когда коммит с такой командой попадает в master , GitHub автоматически закроет указанную задачу. Можно использовать разные формы этой команды: Fix #123 , fixes #123 , close #123 и другие. Это экономит время на поддержку проекта.

В наших проектах нужно использовать Fix #123 или Close #123 на последней строке сообщения коммита.

git log —oneline выводит историю в формате « 1 коммит — 1 строка на экране». При этом он использует в качестве описания коммита первую строку — краткое описание. Поэтому оно обязательно должно быть отделено пустой строкой от остального описания — иначе однострочный вывод разъедется.

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

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

Проверяем изменения

Когда вы сделали правки , стоит их проверить — если только это не что-то абсолютно тривиальное.

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

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

Создаём Pull Request

Когда работа и проверка закончены , пора создавать Pull Request. Pull Request — это запрос на вливание изменений из вашей ветки в основную ветку исходного репозитория. Таким образом они попадут к хозяевам проекта.

Чтобы создать Pull Request, зайдём на страницу вашего форка. Справа от выпадающего меню с выбором ветки есть кнопка « New pull request».

Вы попадаете в окно сравнения веток.

Вот элементы этого окна , по порядку:

1. Базовый репозиторий , в который будет создаваться PR. Это должен быть репозиторий , от которого вы делали форк. Если вы форкнули проект ruRust/rustycrate.ru , а ваше имя пользователя GitHub — user , то у вас будет проект user/rustycrate.ru .
2. Базовая ветка в этом репозитории , обычно master .
3. Репозиторий , откуда должны вливаться изменения. Здесь должен быть выбран репозиторий в вашем аккаунте — user/rustycrate.ru .
4. Ветка , откуда будут вливаться изменения. Это должна быть ветка , которую мы создали в разделе « Создаём ветку».

Дальше просмотрите изменения — то ли это , что вы делали? Если да , то нажимайте кнопку « Create pull request». В моём примере её нет , т. к. ветки в форке и в оригинале находятся в одинаковом состоянии. В вашем же случае внизу будет список коммитов , которые попадут в исходный репозиторий , и , на других вкладках — сами изменения и комментарии к изменениям.

После нажатия кнопки появится окно ввода сообщения Pull Request.

Сообщение PR — это описание того , что сделано и зачем. В отличие от сообщения коммита , здесь уже нужно писать высокоуровневое описание того , какие изменения сделаны. В части « зачем», а также по формату самого сообщения — стоит придерживаться тех же правил , что и в случае с коммитами. Короткий заголовок ( Title), в Comment — описание , а затем служебная информация ( Fix #100500 ). Если вы писали команды закрытия задач в коммитах , здесь можно их не дублировать. Если нет — напишите здесь.

Затем нажимаем « Create pull request». Он создаётся , о нём приходит уведомление людям , поддерживающим проект , и он становится виден в исходном репозитории на вкладке « Pull requests». С этого момента начинается рецензирование изменений ( code review).

Подсказка: если сразу после того , как вы отправили ветку в свой репозиторий ( git push origin ) зайти на страницу репозитория , там будет предложение создать Pull Request на вливание недавно отправленной ветки в master. Сделать это можно как в вашем форке , так и в исходном репозитории. Это будет отдельная кнопка вверху , и при её нажатии в качестве ветки для слияния будет указана та , куда вы делали git push .

Участвуем в Code Review

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

Со стороны автора Pull Request ( а раз вы читаете это руководство , вы наверняка автор) требуется с пониманием относиться к комментариям рецензента — они направлены на повышение качества проекта. Если ошибка в сборке выявляется в процессе рецензирования , это гораздо лучше , чем если она попадёт в репозиторий, а следующий человек , который попытается поучаствовать в проекте , не сможет этого сделать из-за той самой ошибки. Да и это касается не только сборки , разумеется.

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

Если кто-то ведёт себя неадекватно — не медлите. Сначала сообщите об этом собеседнику и призовите его к благоразумию. Если не сработало — смело обращайтесь к рецензенту или к автору данного текста ( Панкову Михаилу — @mkpankov). Это можно сделать в нашем чате.

Пожелание относительно процесса рецензирования — постарайтесь не сильно затягивать с ответами на комментарии или изменением указанных вещей.

Почему это важно? Автор PR хорошо разбирается в том , что он сделал , а если процесс затягивается на недели и месяцы , высока вероятность , что или автор , или рецензент отвлекутся на другие вещи , а обратный вход в контекст изменений тоже стоит усилий и времени. « Другие вещи» здесь — это вся остальная жизнь человека. Может на работе аврал , может личные проблемы , может заболел. В итоге может получиться так , что ваш PR навеки повиснет в неготовом состоянии и так и не будет влит. Конечно , нам бы этого не хотелось.

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

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

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

Когда этот этап завершается , рецензент нажимает кнопку « Merge Pull Request». Ваши изменения влиты в основной репозиторий проекта.

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

Завершение работы

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

Но сначала лучше обновить вашу локальную master-ветку — тогда git убедится, что ваша ветка уже влита в master , и не будет предупреждать , что вы можете потерять свои изменения.

Итак , обновляем нашу локальную рабочую копию. Для этого добавим ещё один remote — так называется удалённый репозиторий. Сейчас он у вас только один — origin , и он указывает на ваш форк. Добавим remote с именем upstream , который будет указывать на исходный репозиторий:

git remote add upstream https://github.com/ruRust/rustycrate.ru.git

URL в конце — это URL того репозитория , который вы форкнули. ( На всякий случай — он написан в небольшом поле справа от переключателя « HTTPS-SSH», правее зелёной кнопки « New pull request».)

Добавив его , можно обновить наш локальный master :

git checkout master git pull --rebase upstream/master

А теперь можно удалить нашу ветку fix-protobaz локально:

git branch -d fix-protobaz

git push --delete origin fix-protobaz

Теперь у нас чистый , обновлённый репозиторий. Можно начинать работу над новым PR.

Если у вас что-то не получилось сделать , или непонятно написано — пишите об этом в чате или создавайте задачи в нашем репозитории.

Если в какой-то момент возникают ошибки — сделайте git status . Очень часто git сам подсказывает , что можно сделать и как это сделать. Если всё равно не получилось — обращайтесь в чат , поможем.

После этой публикации остаются неотвеченные вопросы: как поступать , если случайно закоммитил не в ту ветку; что делать , если кажется , что git потерял ваши изменения; как работать с сервисом code review Reviewable ; как рецензировать чужие изменения и , возможно , другие.

С этими вопросами можно обращаться в чат , а в будущем мы постараемся написать руководства и по этим темам.

Хороших вам коммитов , пусть проект собирается и тесты проходят. Присылайте ваши Pull Request’ы!

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 , поскольку эта ветка фактически принадлежит другому репозиторию.