Как сделать первый пул-реквест на GitHub
Перевод статьи «How to make your first pull request on GitHub».
Что такое форк?
Когда нам нравится чей-то репозиторий и мы хотели бы иметь его в собственном аккаунте на GitHub, мы делаем форк («вилку») этого репозитория, чтобы иметь возможность работать с ним отдельно.
Когда мы делаем форк репозитория, мы получаем экземпляр всего репозитория, со всей его историей. После форка мы можем делать с ним все, что угодно: оригинальная версия при этом не будет задета.
Что такое пул-реквест?
Пул-реквесты нужны. Когда мы хотим принять участие в групповой разработке проектов с открытым исходным кодом.
Например, пользователь Павел делает форк репозитория ThanoshanMV (автора статьи, — прим. перев.) и вносит изменения в свой экземпляр. После этого Павел отсылает пул-реквест ThanoshanMV, который может либо принять его, либо отклонить. По сути это что-то вроде письма «Не будете ли вы так любезны, уважаемый ThanoshanMV, внести мои изменения в свой оригинальный репозиторий?»
Как можно стать контрибьютором проекта?
Участие в проекте с открытым исходным кодом не обязательно предполагает работу именно с кодом. Контрибьютором (участником) можно стать и другими способами, некоторые из них описаны ниже.
Давайте создадим наш первый пул-реквест!
1. Форк репозитория
Чтобы сделать форк репозитория, нужно нажать кнопку «Fork» в верху страницы. Таким образом вы создадите экземпляр всего этого репозитория в своем аккаунте.
2. Клонирование репозитория
Когда репозиторий уже есть в вашем аккаунте, вы можете клонировать его на свою машину и в дальнейшем работать с ним локально.
Чтобы клонировать репозиторий, нажмите кнопку «clone» и скопируйте ссылку.
Откройте терминал и запустите следующую команду. С ее помощью репозиторий будет клонирован на вашу машину.
Теперь у вас есть копия ветки master основного онлайн-репозитория проекта.
Переходим в клонированную директорию:
3. Создание ветки
При работе с репозиторием хорошей практикой считается создание отдельной ветки для внесения изменений, причем это не зависит от размеров проекта.
Имя ветки должно быть коротким и отражать те изменения, которые вы вносите.
Создадим ветку при помощи команды git checkout:
4. Внесение изменений и коммит
Внесите необходимы изменения в проект и сохраните их. Затем запустите команду git status: вы увидите внесенные изменения.
Добавьте эти изменения в только что созданную ветку при помощи команды git add:
Теперь вы можете сделать коммит этих изменений при помощи команды git commit:
5. Отправка изменений на GitHub
Чтобы отправить изменения на GitHub (сделать push), нужно определить имя удаленного репозитория.
Имя данного удаленного репозитория — «origin».
После определения имени можно безопасно отправить изменения на GitHub.
6. Создание пул-реквеста
Перейдите в свой репозиторий на GitHub. Там есть кнопка «Compare & pull request» — кликните ее.
Введите необходимые детали относительно того, что именно вы сделали (чтобы поставить ссылку на issues, возмользуйтесь знаком «решетки»). После этого можно нажать кнопку подтверждения внизу.
Поздравляю! Вы создали свой первый пул-реквест. Если его примут, вы получите уведомление по электронной почте.
7. Синхронизация вашего форка с основной веткой
Прежде чем создавать пул-реквест в оригинальный репозиторий, нужно синхронизировать свой экземпляр этого репозитория с оригинальным.
Даже если вы не собираетесь отправлять пул-реквест в оригинальный репозиторий, все равно лучше синхронизироваться с ним. Со времени создания форка в оригинальном репозитории могли добавиться новые фичи, а также могли быть исправлены какие-то баги.
Проделайте следующие действия, чтобы обновить свой репозиторий и внести соответствующие изменения в свою ветку master:
1. Для начала, проверьте, в какой ветке вы находитесь.
Вы получите список всех веток, причем активная будет подсвечена зеленым.
2. Переключитесь в ветку master.
3. Добавьте оригинальный репозиторий в качестве upstream-репозитория.
Чтобы вытащить изменения из оригинального репозитория и перенести их в свою версию, нужно добавить оригинальный git-репозиторий в качестве upstream-репозитория.
Здесь [HTTPS] это url, который нужно скопировать из основного репозитория.
4. Fetch репозитория
Заберите (fetch) все изменения из оригинального репозитория. Коммиты, сделанные в оригинальном репозитории, будут сохранены в локальной ветке под названием upstream/master.
5. Слейте изменения
Слейте (merge) изменения из upstream/master с вашей локальной веткой master. Таким образом главная ветка вашего форка репозитория синхронизируется с upstream-репозиторием без потери ваших локальных изменений.
6. Отправьте изменения на GitHub
На этом этапе ваша локальная ветка синхронизирована с веткой master оригинального репозитория. Если вы хотите обновить свой GitHub-репозиторий, нужно отправить в него изменения.
Примечание. После синхронизации ветки master вашего форка вы можете при желании удалить remote. Но в будущем вам еще придется обновлять/синхронизировать ваш репозиторий, поэтому лучше его сохранить.
8. Удаление ненужной ветки
Ветки создаются с какими-то конкретными целями. Когда цель достигнута, необходимость в ветке отпадает, поэтому ее можно удалить.
Вы можете удалить и версию этой ветки на GitHub.
Итоги
GitHub это мощный инструмент для контроля истории версий. Каждый может стать контрибьютором проекта с открытым исходным кодом. Делается это путем отправки пул-реквестов.
Чтобы стать контрибьютором, не обязательно писать код: есть и другие способы принять участие в проекте.
Наконец, я хотел бы также сказать, что не стоит переживать, если ваши пул-реквесты отклонят. Мейнтейнеры тратят много времени на улучшение своих проектов и они, безусловно, лучше знают эти проекты, чем вы. Поэтому не стоит переживать, если они решат не вливать в свой проект ваши изменения.
About pull requests
In this article
Pull requests let you tell others about changes you’ve pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch.
About pull requests
Note: When working with pull requests, keep the following in mind:
You can create pull requests on GitHub.com, with GitHub Desktop, in Codespaces, on GitHub for mobile, and when using GitHub CLI.
After initializing a pull request, you’ll see a review page that shows a high-level overview of the changes between your branch (the compare branch) and the repository’s base branch. You can add a summary of the proposed changes, review the changes made by commits, add labels, milestones, and assignees, and @mention individual contributors or teams. For more information, see «Creating a pull request.»
Once you’ve created a pull request, you can push commits from your topic branch to add them to your existing pull request. These commits will appear in chronological order within your pull request and the changes will be visible in the «Files changed» tab.
Other contributors can review your proposed changes, add review comments, contribute to the pull request discussion, and even add commits to the pull request.
You can see information about the branch’s current deployment status and past deployment activity on the «Conversation» tab. For more information, see «Viewing deployment activity for a repository.»
After you’re happy with the proposed changes, you can merge the pull request. If you’re working in a shared repository model, you create a pull request and you, or someone else, will merge your changes from your feature branch into the base branch you specify in your pull request. For more information, see «Merging a pull request.»
If status checks are required for a repository, the required status checks must pass before you can merge your branch into the protected branch. For more information, see «About protected branches.»
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.»
Tips:
You can visit your dashboard to quickly find links to recently updated pull requests you’re working on or subscribed to. For more information, see «About your personal dashboard.»
Draft pull requests
Draft pull requests are available in public repositories with GitHub Free for organizations and legacy per-repository billing plans, and in public and private repositories with GitHub Team, GitHub Enterprise Server 2.17+, and GitHub Enterprise Cloud. For more information, see «GitHub’s products.»
When you create a pull request, you can choose to create a pull request that is ready for review or a draft pull request. Draft pull requests cannot be merged, and code owners are not automatically requested to review draft pull requests. For more information about creating a draft pull request, see «Creating a pull request» and «Creating a pull request from a fork.»
When you’re ready to get feedback on your pull request, you can mark your draft pull request as ready for review. Marking a pull request as ready for review will request reviews from any code owners. You can convert a pull request to a draft at any time. For more information, see «Changing the stage of a pull request.»
Differences between commits on compare and pull request pages
The compare and pull request pages use different methods to calculate the diff for changed files:
Что такое пул-реквесты и зачем они нужны?
Перевод статьи «What’s the Point of Pull Requests Anyway?»
Если вы еще новичок в мире Git и тесно связанных с ним платформ (например, GitHub или GitLab), то вы могли и не слышать таких терминов, как пул-реквест (pull request) или мерж-реквест (merge request). И даже если что-то такое слышали, то можете не знать, что означают эти термины и зачем нужны эти самые «реквесты».
Примечание. В статье я буду использовать термин «пул-реквест», но по сути это то же самое, что мерж-реквест, только последний используется на GitLab.
Пул-реквесты помогают командам создавать программы и распространять их. Чтобы вникнуть в саму идею, придется немного напрячься, но я уверен, что дело того стоит. Моя цель — помочь вам познакомиться с пул-реквестами и рассказать, какое место они занимают в процессе разработки ПО.
Что такое пул-реквест?
Пул-реквест это запрос (англ. request — «запрос») на интеграцию изменений из одной ветки в другую. Причем в ветке может быть всего один коммит одного разработчика, а может быть несколько коммитов разных авторов. В большинстве случаев пул-реквест используется для интеграции нового функционала или для исправления бага в основной ветке проекта.
Пул-реквест также содержит короткое описание изменений и причин, по которым эти изменения вносятся. Обычно между автором пул-реквеста и ревьюерами происходит обсуждение этих изменений.
Ревьюеры — это другие разработчики, работающие над этим проектом и способные дать обратную связь по вносимым изменениям. В проектах с открытым исходным кодом в роли ревьюеров обычно выступают ключевые контрибьюторы или мейнтейнеры. В других случаях (например, в вашей команде на работе) ревьюерами бывают более опытные коллеги (разработчики-сеньоры).
Вот как выглядит пул-реквест с простым описанием и ссылкой на issue (проблему) на GitHub:
Теперь, когда мы дали определение пул-реквестам, давайте посмотрим, почему они столь популярны и чем могут быть полезны.
Коммуникация
По сути пул-реквесты облегчают процесс совместной работы с другими людьми. Они позволяют сделать прозрачной коммуникацию между авторами и ревьюерами путем показа дифф-ов (diffs), коммитов (commits) и комментариев, поясняющих изменения.
До пул-реквестов изменения подтверждались по электронной почте или в IRC-каналах. Там писали название ветки или указывали набор коммитов. Чтобы смержить (слить) изменения, мейнтейнер или выпускающий разработчик должен был сравнить изменения с текущей версией кода на собственном компьютере, дать фидбэк, а потом подождать ответа с дополнительными изменениями. Согласованные изменения мержил на своей локальной машине, а затем отправлял их в общую кодовую базу. Пул-реквесты существенно упрощают весь этот процесс.
Особенно это касается крупных проектов, над которыми работают тысячи контрибьюторов. Поэтому многие из подобных проектов придерживаются именно процедуры пул-реквестов. Часто они также применяют рабочий процесс под названием «GitHub flow». GitHub flow предполагает форки целых проектов и создание пул-реквестов в этих форках.
Поначалу все это кажется страшным и непонятным, но не волнуйтесь! Просто помните, что основная идея остается прежней: вы запрашиваете разрешение на перенос изменений из одной ветки в другую.
Еще одно преимущество процедуры пул-реквестов в том, что всем сотрудникам видна вся коммуникация по изменениям. К вашим услугам поиск по внесенным изменениям и возможность использовать теги. В общем, отслеживать происходящее относительно легко. Контекст и предыдущие решения не теряются где-то в потоках электронных писем или окнах чатов. Любой разработчик, участвующий в проекте, может легко найти и просмотреть нужные сведения.
Автоматизация
Поскольку пул-реквесты приобрели огромную популярность в сообществе разработчиков, GitHub и другие подобные платформы создали обширный набор вебхуков (webhooks), спроектированных на основе GitHub flow. Эти вебхуки делают возможной автоматизацию работы. В наши дни распространена практика, когда задачи непрерывной интеграции выполняются при каждом коммите, и поэтому являются частью пул-реквеста. По своему опыту могу судить, что это одно из самых подходящих мест для автоматизации. Речь идет не только о запуске автоматизированных тестов. Из изменений в пул-реквесте можно разворачивать целые окружения, чтобы проверить, гладко ли все прошло.
Раньше подобные инструменты интеграции были дорогими. Команде или приходилось поддерживать инфраструктуру для задач автоматизации, либо платить за сервисы. В последнее время все больше инструментов становятся доступными, а значит, настройка автоматизированных задач облегчается. Например, вы можете воспользоваться бесплатными предложениями таких компаний как Netlify и Travis.
GitHub пошел даже еще дальше и выпустил GitHub Actions. Actions позволяют вам создавать рабочие процессы автоматизации из набора отдельных маленьких задач, пригодных для компоновки. Непременно попробуйте!
Проверки статуса
Последнее большое преимущество пул-реквестов это концепция проверок статуса (status checks). Проверки статуса это просто набор задач, выполняемых для каждого коммита в пул-реквесте, и выдающих результат «успех» (success) или «провал» (failure). Это буквально чек-листы для проверки того, готовы ли изменения к отправке в кодовую базу.
Проверять можно что угодно. В большинстве команд проверки статуса состоят из автоматизированных тестов, за которыми следует проверка стиля, после которой проверяется, получил ли этот код одно или два одобрения на ревью. Изменения не могут быть слиты, пока не пройдут все эти проверки.
Стоит также остановиться на теме код-ревью. Поскольку пул-реквесты сильно улучшают возможности коммуникации и сотрудничества, естественно, что многие команды применят их в код-ревью. Таким образом прямо со страницы пул-реквеста можно осуществлять менеджмент ревьюеров, ревью и статуса запросов (одобрено или нет). Во многих крупных проектах есть даже автоматическая процедура добавления отдельных пользователей или групп к пул-реквесту — в зависимости от файлов, которые были изменены. Если хотите пример, посмотрите документацию CODEOWNERS.
Итоги
Если брать коротко, пул-реквест это просто запрос на внедрение изменений из одной ветки в другую. Несмотря на простоту концепции, пул-реквесты являются очень мощным инструментом. Именно поэтому они стали важной частью современной разработки. Пул-реквесты облегчают задачи непрерывной интеграции, код-ревью и проверки статуса, а все вместе это позволяет поддерживать высокий уровень качества кода.
Если раньше репозиторий был просто местом, где хранится код, то с появлением пул-реквестов он стал местом, где хранятся знания об этом коде.
Также пул-реквесты играют большую роль в процессе обучения. Некоторые из самых важных уроков, касающихся разработки программ, я получил в фидбэках терпеливых ревьюеров моих пул-реквестов.
Как организовать сотрудничество на GitHub
Если вы еще не в курсе, GitHub это очень эффективный способ организации совместной работы над проектами.
Данный сервис предоставляет каждому, у кого есть доступ в интернет, возможность делиться кодом со всеми остальными пользователями, совершенно бесплатно (не говоря уже о вспомогательных средствах для проверки исходного кода и просмотра истории внесенных изменений). GitHub был принят множеством проектов с открытым кодом, как платформа для их совместной разработки и улучшения.
В этой статье мы обсудим некоторые правила работы над такими проектами, а также дадим необходимые знания и инструкции для начинающих.
Начните с малого
Начиная работать над проектом с открытым кодом, очень важно определить свою роль. На самом деле, люди нередко отказываются от участия в разработке только потому, что боятся показаться не слишком опытными и знающими программистами.
Не бойтесь начать с малого : вместо того, чтобы пытаться исправить большие ошибки ( баги ) или переписать целый модуль, попробуйте найти недостатки в документации или ошибки кроссплатформенности, или даже простые синтаксические и грамматические ошибки ( пример на GitHub от пользователя mzgol).
Изучите экосистему проекта
При любой совместной работе, как правило, вводится набор соглашений. Среди них может быть методика внесения изменений, график работы или даже синтаксические стандарты и правила форматирования. Перед тем, как начинать реальную работу над проектом, прочитайте всю имеющуюся документацию.
Например, GitHub стандартизовал файл CONTRIBUTING.md (ознакомьтесь для примера с этим документом ). Подобные инструкции поддерживаются людьми, которые обслуживают базы кодов.
Другим способом понимания экосистемы проекта, является просмотр имеющейся базы кода и просмотр истории коммитов (изменений). Прочтение сообщений об изменениях и просмотр стиля кода может рассказать вам многое о проекте. Ознакомьтесь с документацией и словарями, чтобы внесенные вами изменения имели стиль, схожий с используемым в данном проекте.
Теперь, когда вы являетесь частью экосистемы проекта, как же вам все-таки внести изменения?
Использование Pull-Request для внесения изменений
Первое, что следует уяснить, это важность следования стандартам и соглашениям, принятым в проекте, над которым вы работаете (что уже обсуждалось выше). Стандартная рабочая среда на GitHub достаточно проста и позволяет:
Некоторые проекты используют короткие сообщения с правками, другие же – более длинные. Далее приведена пошаговая инструкция, которая поможет разобраться с интерфейсом и функционалом.
Это блог
Расскажу, как быстро и просто открыть пулл-реквест, на что обратить внимание, и сделать так, чтобы ваш ревьюер не расстраивался. В конце статьи есть чеклист, чтобы быстро проверять по нему.
Предполагаю, что вы уже форкнули проект, склонировали себе форк, что-то там накоммитили и готовы открыть пулл-реквест. Лучше всего читать эту статью параллельно с открыванием пулл-реквеста.
Найдите кнопку «Pull Request»
Не суетитесь и не бегайте по репозиториям, переключая ветки. Сразу, как вы запушили, на главной страничке вашего репозитория появится жёлтая плашка с названием ветки и кнопкой «Compare & pull request».
Эта кнопка — самый короткий путь к открытию пулл-реквеста. Жмите её.
Проверьте ветки
После нажатия кнопки у вас откроется подробная страничка о том, откуда и куда вы открываете пулл-реквест. Посмотрите, куда вольётся ваш код. Он должен попадать в главную ветку основного репозитория. Скорее всего это ветка master. И он должен быть из вашего форка и ветки, в которой вы делали работу.
Куда и откуда попадёт код
Скорее всего так и есть, если вы правильную кнопку нажали.
Проверьте конфликты
Прямо под ветками написано, есть конфликты или нет:
Вот тут нет конфликтов
Бывает, что конфликты есть:
Хорошим тоном считается открывать пулл-реквесты без конфликтов. Поэтому если у вас конфликт, решите его до того, как откроете пулл-реквест. Можно отребейзить вашу ветку от мастера главного репозитория, или можно влить мастер главного репозитория в вашу ветку.
Если вы работаете в команде и не умеете решать конфликты, попросите старшего товарища вам помочь. А если вы студент, попросите наставника 🙂 Вы так же можете сначала открыть пулл-реквест, пусть и с конфликтами, а потом эти конфликты решить.
Напишите заголовок и описание
В форме открытия пулл-реквеста напишите заголовок: коротко что вы сделали. И описание: что конкретно и зачем, а что ещё не доделано.
Проверьте изменённые файлы
Изменённые файлы (дифф)
Почитайте сами свой дифф и проверьте, не попалось ли там чего лишнего. Мог закрасться лишний файл, или вы закомментировали кусок кода, а потом забыли раскомментировать.
На скриншоте выше файл npm-debug.log.1955635711 очевидно лишний. Значит нужно его удалить и закоммитить это, и снова запушить в эту ветку. Если вы нашли ошибку, то просто исправьте её, закоммитьте и запушьте. Потом обновите страничку с диффом и убедитесь, что всё в порядке.
Теперь жмите «Create pull request»! Ура!
Как открыть пулл-реквест:
Подписывайтесь на телеграм-канал про фронтенд, дизайн, работу и жизнь.
