How to Be a GitHub Contributor in Five Minutes
This article shows you how to contribute to your first open source project in just five minutes.
Before You Start
First of all, you need a GitHub account to be a contributor.
If you don’t have a GitHub account, or aren’t sure what Git is, please refer to the official website first.
How to Be a GitHub Contributor
Generally speaking, you need to go through the following steps to become a contributor:
- Fork a repo
- Clone the repo
- Define a pre-commit hook
- Create a branch
- Read the code and documentation style
- Develop
- Push changes to GitHub
- Create pull request
- Ask for a code review
Let’s look at the steps one by one with the example of our Nebula Graph repo.
Fork a repo
Fork the Nebula Graph repo by clicking on the fork button on the top of the main page. This will create a copy of this repository in your account.
You can see nebula repository is in your repository list. Please be noted the information This branch is 117 commits behind vesoft-inc:master. , which indicates the deference between your branch and the master. If you just forked the repository, the information is This branch is even with vesoft-inc:master.
Clone the Repository
Clone the repository to your local machine. Click the Clone or download button, then click the copy to clipboard icon. Your remote repo on Github is called origin.
Open a terminal and run the following git command:
where “url you just copied” (without the quote marks) is the url to the Nebula Graph repository. See the previous picture to obtain the url. For example:
where nebula-package is the user name.
Define a Pre-Commit Hook
Please link the Nebula Graph pre-commit hook into your .git directory. This hook checks your commits for formatting, building, doc generation, etc.
Create a Branch
Switch to the Nebula Graph repository directory and create a new branch named myfeature to work on!
Code and Documentation Style
You can implement/fix your feature, comment your code in your myfeature branch now. Please follow the Google C++ Style Guide style and Documentation Style Guide.
We are using the clang-format to format the code. It is recommended that you configure it according to the IDE/editor you use. See how to configure clang-format with vim/emacs/vscode.
Develop
Edit your code and commit the changes with the following command.
Push Changes to GitHub
When ready to review (or just to establish an offsite backup or your work), push your branch to your fork on github.com :
Create Pull Request
- Visit your fork at https://github.com/$user/nebula (replace $user obviously).
- Click the Compare & pull request button next to your myfeature branch.
Ask for a Code Review
Once your pull request has been opened, it will be assigned to at least two reviewers. Those reviewers will do a thorough code review to ensure the changes meet the repository’s contributing guidelines and other quality standards.
Once the pull request is approved and merged you can pull the changes from upstream to your local repo and delete your extra branch(es).
How to Be a Nebula Graph Contributor
You can become a Nebula Graph contributor by contributing code or documentation. This section shows you how to raise doc pr to be our contributor. The follow picture shows the doc toc and you can make changes in any of the .md doc files. Consider the Get Started doc as example.
Example: Get Started
The above picture shows the change log of the doc. You can add details, fix errors or even rewrite the whole doc to make it more organized and readable.
Please refer to the Documentation Toc to see all the Nebula Graph docs.
Last but not least, you are welcome to try Nebula Graph at our GitHub Repository. If you have any problems or suggestions please raise us an issue.
If this post was helpful, please click the clap �������� button below a few time to show your support! ��������
6.3 GitHub — Сопровождение проекта
Теперь, когда вы комфортно себя чувствуете при участии в проекте, давайте посмотрим на другую сторону вопроса: создание, сопровождение и администрирование вашего собственного проекта.
Создание нового репозитория
Давайте создадим новый репозиторий для распространения кода нашего проекта. В панели управления справа нажмите кнопку «New repository» или воспользуйтесь кнопкой + на панели инструментов, рядом с вашим именем пользователя как показано на рисунке Выпадающее меню «New repository».
Это приведёт к открытию формы «New repository»:
Всё, что в действительности нужно сделать, так это указать название проекта, все остальные поля опциональны. Сейчас, просто нажмите кнопку «Create Repository» и ваш новый репозиторий с названием <пользователь>/<имя_проекта> готов.
Так как в репозитории ещё нет кода, GitHub отобразит инструкции о том, как создать совершенно новый репозиторий или подключить существующий Git проект. Здесь мы не будем этого делать; если вам нужно освежить память, смотрите главу Основы Git.
Теперь ваш проект хостится на GitHub и вы можете предоставить ссылку на него любому желающему. Все проекты на GitHub доступны как по HTTP https://github.com/<user>/<project_name> , так по SSH git@github.com:<user>/<project_name> . Git может получать и отправлять изменения по обоим указанным ссылкам, при этом производится контроль доступа на основании учётных данных пользователя, осуществляющего подключение.
Обычно, для общедоступного проекта предпочтительнее использовать HTTPS ссылки, так как это не требует наличия GitHub аккаунта для клонирования репозитория. При этом, для использования SSH ссылки у пользователя должен быть GitHub аккаунт и его SSH ключ должен быть добавлен в ваш проект. Так же HTTPS ссылка полностью совпадает с URL адресом, который пользователи могут вставить в браузер для просмотра вашего репозитория.
Добавление участников
Если вы работаете с другими людьми, которым вы хотите предоставить доступ для отправки коммитов, то вам следует добавить их как «участников». Если Бен, Джефф и Льюис зарегистрировались на GitHub и вы хотите разрешить им делать «push» в ваш репозиторий, то добавьте их в свой проект. Это предоставит им «push» доступ; это означает, что они будут иметь права доступа как на чтение, так и на запись в проект и Git репозиторий.
Перейдите по ссылке «Settings» в нижней части панели справа.
Затем выберите «Collaborators» в меню слева. Напишите имя пользователя в поле для ввода и нажмите кнопку «Add collaborator». Так вы можете добавить неограниченное количество пользователей. Чтобы отозвать доступ, просто нажмите «X» справа от имени пользователя.
Управление запросами на слияние
Сейчас у вас есть проект с некоторым кодом и, возможно, несколько участников с «push» доступом, давайте рассмотрим ситуацию, когда вы получаете запрос на слияние.
Запрос на слияние может быть как из ветки вашего репозитория, так и из ветки форка вашего проекта. Отличаются они тем, что вы не можете отправлять изменения в ветки ответвлённого проекта, а его владельцы не могут отправлять в ваши, при этом для внутренних запросов на слияние характерно наличие доступа к ветке у обоих пользователей.
Для последующих примеров предположим, что вы «tonychacon» и создали новый проект для Arduino с названием «fade».
Email уведомления
Кто-то вносит изменения в ваш код и отправляет вам запрос на слияние. Вы должны получить письмо с уведомлением о новом запросе слияния, которое выглядит как на Email уведомление о новом запросе слияния.
Следует сказать о некоторых особенностях этого уведомления. В нем содержится краткая статистика отличий — количество изменений и список файлов, которые были изменены в этом запросе слияния, ссылка на страницу запроса слияния на GitHub, а так же несколько ссылок, которые вы можете использовать в командной строке.
Если вы видите строку с текстом git pull <url> patch-1 , то это самый простой способ слить удалённую ветку без добавления удалённого репозитория. Это кратко описывалось в Извлечение удалённых веток. Если хотите, то можно сначала переключиться в тематическую ветку и только потом выполнить эту команду для изменений запроса слияния.
Другие ссылки, которые представляют интерес, это .diff и .patch ссылки. Как вы догадались, они указывают на версии унифицированной разницы и патча запроса слияния. Технически, вы можете слить изменения из запроса слияния командой:
Взаимодействие по запросу слияния
Как описано в разделе Рабочий процесс с использованием GitHub главы 6, вы можете общаться с тем, кто открыл запрос на слияние. Вы можете добавлять комментарии к отдельным строкам кода, коммитам или ко всему запросу целиком, используя усовершенствованную разметку GitHub где угодно.
Каждый раз, когда кто-то другой оставляет комментарий к запросу слияния, вы будете получать email уведомления по каждому событию. Каждое уведомление будет содержать ссылку на страницу запроса слияния где была зафиксирована активность и, чтобы оставить комментарий в основной ветке запроса на слияние, вы можете просто ответить на это письмо.
Когда вы готовы слить код, вы можете стянуть его себе и слить локально, слить используя команду git pull <url> <branch> , которую мы видели ранее, или добавив ответвлённый репозиторий как удалённый получить и слить изменения.
Если слияние тривиально, то можно просто нажать кнопку «Merge» на сайте GitHub. Это всегда приводит с созданию коммита слияния, даже если доступно слияние перемоткой вперёд. Это значит, что в любом случае создаётся коммит слияния, как только вы нажимаете кнопку «Merge». Как можно увидеть на Кнопка Merge и инструкции по ручному слиянию запроса, GitHub отображает информацию об этом при вызове подсказки.
Если вы решаете не сливать запрос, то вы можете просто закрыть запрос на слияние, а открывший его участник будет уведомлен.
Ссылки на запрос слияния
Если у вас много запросов слияния и вы не хотите добавлять пачку удалённых репозиториев или постоянно делать однократный «pull», то у GitHub есть хитрый трюк, позволяющий это делать. Этот трюк очень сложный, но полезный и мы рассмотрим его немного позже в Спецификации ссылок.
Фактически, GitHub представляет ветки запросов слияния как псевдоветки на сервере. По умолчанию, они не копируются при клонировании, а существуют в замаскированном виде и вы можете легко получить доступ к ним.
В качестве примера мы используем низкоуровневую команду ls-remote (часто упоминается как «plumbing» команда, более подробно о ней будет рассказано в Сантехника и Фарфор). Обычно, эта команда не используется в повседневных Git операциях, но сейчас поможет нам увидеть какие ссылки присутствуют на сервере.
Если выполнить её относительно использованного ранее репозитория «blink», мы получим список всех веток, тегов и прочих ссылок в репозитории.
Аналогично, если вы, находясь в своём репозитории, выполните команду git ls-remote origin или укажете любой другой удалённый репозиторий, то результат будет схожим.
Если репозиторий находится на GitHub и существуют открытые запросы слияния, то эти ссылки будут отображены с префиксами refs/pull/ . По сути это ветки, но так как они находятся не в refs/heads/ , то они не копируются при клонировании или получении изменений с сервера — процесс получения изменений игнорирует их по умолчанию.
Для каждого запроса слияния существует две ссылки, одна из которых записана в /head и указывает на последний коммит в ветке запроса на слияние. Таким образом, если кто-то открывает запрос на слияние в наш репозиторий из своей ветки bug-fix , которая указывает на коммит a5a775 , то в нашем репозитории не будет ветки bug-fix (так как она находится в форке), при этом у нас появится pull/<pr#>/head , которая указывает на a5a775 . Это означает, что мы можем стянуть все ветки запросов слияния одной командой не добавляя набор удалённых репозиториев.
Теперь можно получить ссылки напрямую.
Эта команда указывает Git: «Подключись к origin репозиторию и скачай ссылку refs/pull/958/head ». Git с радостью слушается и выкачивает всё необходимое для построения указанной ссылки, а так же устанавливает указатель на коммит в .git/FETCH_HEAD . Далее, вы можете слить изменения в нужную ветку при помощи команды git merge FETCH_HEAD , однако сообщение коммита слияния будет выглядеть немного странно. Так же это становится утомительным, если вы просматриваете много запросов на слияние.
Существует способ получать все запросы слияния и поддерживать их в актуальном состоянии при подключении к удалённому репозиторию. Откройте файл .git/config в текстовом редакторе и обратите внимание на секцию удалённого репозитория origin . Она должна выглядеть как-то так:
Строка, начинающаяся с fetch = , является спецификацией ссылок («refspec»). Это способ сопоставить названия в удалённом репозитории и названиями в локальном каталоге .git . Конкретно эта строка говорит Git: «все объекты удалённого репозитория из refs/heads должны сохраняться локально в refs/remotes/origin ». Вы можете изменить это поведение добавив ещё одну строку спецификации:
Последняя строка говорит Git: «Все ссылки, похожие на refs/pull/123/head , должны быть сохранены локально как refs/remotes/origin/pr/123 ». Теперь, если сохранить файл и выполнить команду git fetch , вы получите:
Все запросы слияния из удалённого репозитория представлены в локальном репозитории как ветки слежения; они только для чтения и обновляются каждый раз при выполнении git fetch . Таким образом, локальное тестирование кода запроса слияния становится очень простым:
Особо внимательные из вас заметили head в конце спецификации, относящейся к удалённому репозиторию. Так же на стороне GitHub существует ссылка refs/pull/#/merge , которая представляет коммит, формируемый при нажатии кнопки «merge» на сайте. Это позволяет вам протестировать слияние перед нажатием этой кнопки.
Запросы слияния на запросы слияния
Вы можете открыть запрос слияния не только в ветку master , запросы слияния могут указывать на любую ветку любого репозитория в сети. По сути, вы можете даже открыть запрос слияния, указывающий на другой запрос слияния.
Если вы видите толковый запрос слияния и у вас есть идея как его улучшить или вы не уверены, что это хорошая идея, или у вас просто нет прав записи в целевую ветку, то в таком случае вы можете открыть запрос слияния, указывающий на данный запрос.
При открытии запроса на слияние вверху страницы вы увидите меню для выбора целевой и исходной веток. Если нажать кнопку Edit справа, то станет доступным выбор не только исходной ветки, а ещё и форка.
Здесь можно указать вашу новую ветку для слияния с другим запросом слияния или другим форком проекта.
Упоминания и уведомления
GitHub обладает отличной встроенной системой уведомлений, которая может пригодиться для решения вопросов или получения обратной связи от конкретных людей или команд.
В любом комментарии можно написать символ @ , что автоматически вызовет список автодополнения с именами пользователей, которые включены в проект или просто участвуют в нём.
Так же можно упомянуть пользователя, не указанного в выпадающем списке, но с помощью автодополнения это можно сделать быстрее.
Как только вы оставите комментарий с упоминанием пользователя, ему будет отправлено уведомление. Таким образом, можно более эффективно вовлекать пользователей в обсуждение, не опрашивая их непосредственно. Очень часто в запросах слияния на GitHub пользователи приглашают других людей в свои команды или кампании для рецензии проблем или запросов слияния.
Если кто-то будет упомянут в запросе слияния или проблеме, то он автоматически «подписывается» и будет получать уведомления о последующей активности. Вы так же будете подписаны на некоторые уведомления если просто откроете запрос слияния или проблему, станете отслеживать репозиторий или если оставите комментарий. Для прекращения отправки вам уведомлений нажмите кнопку «Unsubscribe».
Страница уведомлений
Когда мы говорим «уведомления» в контексте GitHub, мы имеем ввиду способ, которым GitHub пытается связаться с вами в случае возникновения каких-либо событий, настроить который можно несколькими способами. Для просмотра настроек уведомлений перейдите на закладку «Notification center» на странице настроек.
Доступны два вида уведомлений: посредствам «Email» и «Web». Вы можете выбрать один, ни одного или оба, если активно участвуете в событиях отслеживаемых репозиториев.
Web уведомления
Такие уведомления существуют только на GitHub и посмотреть их можно только на GitHub. Если эта опция включена у вас в настройках и уведомление сработало для вас, то вы увидите небольшую синюю точку на иконке уведомлений вверху экрана, как показано на рисунке Центр уведомлений.
Кликнув по иконке, вы увидите список всех уведомлений, сгруппированных по проектам. Вы можете фильтровать уведомления по конкретному проекту, кликнув по его названию на боковой панели слева. Так же вы можете подтверждать получение уведомлений, кликнув по галочке рядом с любым из уведомлений, или подтвердить все уведомления по проекту, кликнув по галочке в шапке группы. После каждой галочки так же есть кнопка отключения, кликнув по которой вы перестанете получать уведомления по данному элементу.
Эти инструменты очень полезны при обработке большого числа уведомлений. Продвинутые пользователи GitHub полностью отключают email уведомления и пользуются этой страницей.
Email уведомления
Email уведомления — это ещё один способ, которым вы можете получать уведомления от GitHub. Если эта опция включена, то вы будете получать по письму на каждое уведомление. Примеры вы видели в разделах Комментарии, отправленные по электронной почте и Email уведомление о новом запросе слияния. Письма объединяются в цепочки, что очень удобно при использовании соответствующего почтового клиента.
GitHub включает много дополнительных метаданных в заголовки каждого письма, что полезно при настройке различных фильтров и правил сортировки.
Например, если взглянуть на заголовки письма, отправленного Тони в примере Email уведомление о новом запросе слияния, то можно увидеть следующее:
Здесь можно увидеть несколько интересных вещей. Если вы хотите выделить или перенаправить письма конкретного проекта или запроса на слияние, то информация, содержащаяся в заголовке Message-ID , предоставляет вам соответствующие сведения в формате <пользователь>/<проект>/<тип>/<идентификатор> . Для задачи вместо «pull» будет указано «issues».
Заголовки List-Post и List-Unsubscribe , при наличии у вас почтового клиента, который их понимает, позволяют легко написать в список рассылки или отписаться от неё. Это то же самое, что и нажать кнопку «mute» в веб версии уведомлений или «Unsubscribe» на странице задачи или запроса на слияние.
Если включены оба типа уведомлений и ваш почтовый клиент отображает картинки, то при просмотре email версии уведомления, веб версия так же будет отмечена как прочитанная.
Особенные файлы
Существует несколько особенных файлов, которые GitHub заметит при наличии их в вашем репозитории.
README
Первый — это файл README , он может быть в любом формате, который GitHub в состоянии распознать. Например, это может быть README , README.md , README.asciidoc и так далее. Если GitHub увидит такой файл в вашем исходном коде, то отобразит его на заглавной странице проекта.
Большинство команд используют его для поддержания актуальной информации о проекте для новичков. Как правило, он включает следующее:
Для чего предназначен проект
Инструкции по конфигурации и установке
Правила участия в проекте
В этот файл можно встраивать изображения или ссылки для простоты восприятия информации.
CONTRIBUTING
Следующий файл — это CONTRIBUTING . Если в вашем репозитории будет файл CONTRIBUTING с любым расширением, то GitHub будет показывать ссылку на него при создании любого запроса на слияние.
Идея состоит в том, что вы можете указать конкретные вещи, которые вы хотите или не хотите видеть в новых запросах на слияние. Таким образом люди могут ознакомится с руководством, перед тем как создавать новый запрос на слияние.
Управление проектом
Для одного проекта не так уж и много администраторских действий, но есть несколько стоящих внимания.
Изменение основной ветки
Если вы используете в качестве основной другую ветку, отличную от «master», и хотите, чтобы пользователи открывали запросы на слияние к ней, то это можно изменить в настройках репозитория на закладке «Options».
Просто выберите нужную ветку из выпадающего меню и она станет основной для большинства операций, включая извлечение кода при клонировании репозитория.
Передача проекта
Если вы хотите передать проект другому пользователю или организации на GitHub, то это можно сделать нажатием кнопки «Transfer ownership» в настройках репозитория на закладке «Options».
Эта опция полезна, когда вы хотите отказаться от проекта, а кто-то другой хочет им заниматься, или когда ваш проект растёт и вы хотите передать его какой-нибудь организации.
Это действие приведёт не только к передаче репозитория со всеми его подписчиками и звёздами, но и добавит перенаправление с вашего URL на новый. Кроме этого, изменятся ссылки для клонирования и получения изменений из Git, а не только для веб запросов.
Step-by-step guide to contributing on GitHub
Have you thought about contributing to an open source project, but you're too confused (or intimidated) by the process to even try? I've been there too!
I wrote this step-by-step guide to show the exact process I use when contributing to a project on GitHub. If you follow this guide exactly, you can make your first open source contribution TODAY!
Why contribute to open source?
There are many great reasons to contribute to open source projects:
- It builds your resume by demonstrating that you can collaborate with others on code.
- It gives you practice with Git and GitHub, which is a valuable data science skill.
- It helps you to build relationships in the open source community.
- It feels good to give back to a project that you use!
In the example below, I'm going to contribute to Python's scikit-learn library. I've been teaching Machine Learning with scikit-learn for many years, so I'm more than happy to give back!
Getting started
First, you need to choose a project to contribute to. I suggest you start with a library you currently use, because you will already understand the purpose of the library and you will be invested in making it better.
Second, you need to choose how to contribute. I suggest contributing to the project documentation, since it doesn't require writing any code. Start by finding a typo or a broken link to fix. Since this should be a simple fix, you will be able to focus on learning the contribution workflow.
Once you've chosen what to fix, you can begin the step-by-step process below:
- Steps 1 through 6 are setup steps, meaning you only have to do them once for each GitHub project.
- Steps 7 through 19 should be repeated for each contribution to that project.
These resources might be helpful to you as you work through the steps:
- If you're new to Git, watch my 36-minute video series to learn the basic Git commands and terminology.
- If you just need a quick refresher on Git, scan through my Git quick reference guide.
Step 1: Sign into GitHub
Sign into your GitHub account, or create a free GitHub account if you don't have one.
Step 2: Fork the project repository
Find the project's repository on GitHub, and then "fork" it by clicking the Fork button in the upper right corner:
This creates a copy of the project repository in your GitHub account. In the upper left corner, you will see that you are now looking at a repository in your account:
Step 3: Clone your fork
While still in your repository, click the green Clone or download button and then copy the HTTPS URL:
Using Git on your local machine, clone your fork using the URL you just copied: git clone URL_OF_FORK .
For example, I used git clone https://github.com/justmarkham/scikit-learn.git .
Cloning copies the repository files (and commit history) from GitHub to your local machine. The repository will be downloaded into a subdirectory of your working directory, and the subdirectory will have the same name as the repository.
(If you run into problems during this step, read the Set up Git page from GitHub's documentation.)
Step 4: Navigate to your local repository
Since the clone was downloaded into a subdirectory of your working directory, you can navigate to it using: cd NAME_OF_REPOSITORY .
For example, I used cd scikit-learn .
Step 5: Check that your fork is the "origin" remote
You are going to be synchronizing your local repository with both the project repository (on GitHub) and your fork (also on GitHub). The URLs that point to these repositories are called "remotes". More specifically, the project repository is called the "upstream" remote, and your fork is called the "origin" remote.
When you cloned your fork, that should have automatically set your fork as the "origin" remote. Use git remote -v to show your current remotes. You should see the URL of your fork (which you copied in step 3) next to the word "origin".
If you don't see an "origin" remote, you can add it using: git remote add origin URL_OF_FORK .
(If you run into problems during this step, read the Managing remote repositories page from GitHub's documentation.)
Step 6: Add the project repository as the "upstream" remote
Go to your fork on GitHub, and click the "forked from" link to return to the project repository:
While in the project repository, click the green Clone or download button and then copy the HTTPS URL:
Add the project repository as the "upstream" remote using: git remote add upstream URL_OF_PROJECT .
For example, I used git remote add upstream https://github.com/scikit-learn/scikit-learn.git .
Use git remote -v to check that you now have two remotes: an origin that points to your fork, and an upstream that points to the project repository.
This diagram summarizes the entire setup process (steps 1 through 6):
Step 7: Pull the latest changes from upstream into your local repository
Before you start making any changes to your local files, it's a good practice to first synchronize your local repository with the project repository. Use git pull upstream master to "pull" any changes from the "master" branch of the "upstream" into your local repository. (If the project repository uses "main" instead of "master" for its default branch, then you would use git pull upstream main instead.)
If you forked and cloned the project repository just a few minutes ago, it's very unlikely there will be any changes, in which case Git will report that your local repository is "already up to date". But if there are any changes, they will automatically be merged into your local repository.
Step 8: Create a new branch
Rather than making changes to the project's "master" branch, it's a good practice to instead create your own branch. This creates an environment for your work that is isolated from the master branch.
Use git checkout -b BRANCH_NAME to create a new branch and then immediately switch to it. The name of the branch should briefly describe what you are working on, and should not contain any spaces.
For example, I used git checkout -b doc-fixes because I was making some small fixes to the documentation.
Use git branch to show your local branches. You should see your new branch as well as "master", and your new branch should have an asterisk next to it to indicate that it's "checked out" (meaning that you're working in it).
Step 9: Make changes in your local repository
Use a text editor or IDE to make the changes you planned to the files in your local repository. Because you checked out a branch in the previous step, any edits you make will only affect that branch.
Step 10: Commit your changes
After you make a set of changes, use git add -A to stage your changes and git commit -m "DESCRIPTION OF CHANGES" to commit them.
For example, I used git commit -m "fix typos in set_config docstring" for one of my commits.
If you are making multiple sets of changes, it's a good practice to make a commit after each set.
Step 11: Push your changes to your fork
When you are done making all of your changes, upload these changes to your fork using git push origin BRANCH_NAME . This "pushes" your changes to the "BRANCH_NAME" branch of the "origin" (which is your fork on GitHub).
For example, I used git push origin doc-fixes .
Step 12: Begin the pull request
Return to your fork on GitHub, and refresh the page. You may see a highlighted area that displays your recently pushed branch:
Click the green Compare & pull request button to begin the pull request.
(Alternatively, if you don't see this highlighted area, you can switch to your branch using the Branch button and then click the New pull request button.)
Step 13: Create the pull request
When opening a "pull request", you are making a "request" that the project repository "pull" changes from your fork. You will see that the project repository is listed as the "base repository", and your fork is listed as the "head repository":
Before submitting the pull request, you first need to describe the changes you made (rather than asking the project maintainers to figure them out on their own). You should write a descriptive title for your pull request, and then include more details in the body of the pull request. If there are any related GitHub issues, make sure to mention those by number. The body can include Markdown formatting, and you can click the Preview tab to see how it will look.
On the right side, you may see a link to the project's Contributing guidelines. This is primarily worth reading through if you are submitting substantial code (rather than just fixing a typo), but it may still be worth scanning through at this point.
Below the pull request form, you will see a list of the commits you made in your branch, as well as the "diffs" for all of the files you changed.
If everything looks good, click the green Create pull request button!
This diagram summarizes the entire pull request process process (steps 7 through 13):
Step 14: Review the pull request
You have now created a pull request, which is stored in the project's repository (not in your fork of the repository). It's a good idea to read through what you wrote, as well as clicking on the Commits tab and the Files changed tab to review the contents of your pull request:
If you realize that you left out some important details, you can click the 3 dots in the upper right corner to edit your pull request description.
Step 15: Add more commits to your pull request
You can continue to add more commits to your pull request even after opening it! For example, the project maintainers may ask you to make some changes, or you may just think of a change that you forgot to include:
Start by returning to your local repository, and use git branch to see which branch is currently checked out. If you are currently in the master branch (rather than the branch you created), then use git checkout BRANCH_NAME to switch. For example, I used git checkout doc-fixes .
Then, you should repeat steps 9 through 11: make changes, commit them, and push them to your fork.
Finally, return to your open pull request on GitHub and refresh the page. You will see that your new commits have automatically been added to the pull request:
Step 16: Discuss the pull request
If there are questions or discussion about your pull request from the project maintainers, you can add to the conversation using the comment box at the bottom of the pull request:
If there are inline comments about specific changes you made, you can respond to those as well:
Click the Resolve conversation button once you have addressed any specific requests.
Step 17: Delete your branch from your fork
If the project maintainers accept your pull request (congratulations!), they will merge your proposed changes into the project's master branch and close your pull request:
You will be given the option to delete your branch from your fork, since it's no longer of any use:
Click the Delete branch button:
Step 18: Delete your branch from your local repository
You should also delete the branch you created from your local repository, so that you don't accidentally start working in it the next time you want to make a contribution to this project.
First, switch to the master branch: git checkout master .
Then, delete the branch you created: git branch -D BRANCH_NAME . For example, I used git branch -D doc-fixes .
Step 19: Synchronize your fork with the project repository
At this point, your fork is out of sync with the project repository's master branch.
To get it back in sync, you should first use Git to pull the latest changes from "upstream" (the project repository) into your local repository: git pull upstream master .
Then, push those changes from your local repository to the "origin" (your fork): git push origin master .
If you return to your fork on GitHub, you will see that the master branch is "even" with the project repository's master branch:
This step is not strictly necessary, since you will pull changes from upstream before you make your next contribution to this project (step 7). However, this step is useful if you are going to clone your fork from another machine.
Congratulations!
Congratulations on making your first open source contribution! 🎉 Please share a link to your successful pull request in the comments section below. If you ran into any unexpected problems, I'd love to hear about it so that I can continue to improve this guide.
Tips for contributing code
If you're ready to start making code contributions (beyond just fixing typos), here are a few tips:
Introducing Contributions
Today we’re happy to release Contributions: a new addition to profile pages
that lets you see what everyone has been up to on GitHub.
Popular Repositories
Show off the fancy repositories you’ve created. Your repositories with the most stars and watchers make it to the top of this list.
Repositories Contributed To
You’re making contributions to projects all over GitHub and we want to show everyone what you’re doing. Whenever you commit to a project’s default branch or the gh-pages branch, open an issue, or propose a Pull Request, we’ll count that as a contribution. Repositories are sorted by your recent impact. A commit today is worth more than a commit last week.
This also makes it easier to see what others are working on in your Organization. Any repositories you have in common with the profile you’re viewing are shown in this list.
Contributions Calendar
The contributions calendar shows how frequently you’ve been contributing over the past year. We’ve had a great time with this internally. We’ve been annotating our ships, vacations, talks and even graduations! Here’s our very own Tim Clem‘s annotated calendar.
Contribution Activity
Contribution activity is a great way to see what someone has been up to on GitHub. You can see a really concise view of proposed Pull Requests, open issues and commits.