pull-request-tutorial-for-students
A Visual Guide to Pull Requests for my students. The simple way 😊
Project maintained by michalczukm Hosted on GitHub Pages — Theme by mattgraham
Pull Request Tutorial
This tutorial is fork 🍴 from github.com/yangsu/pull-request-tutorial
Send 💙 there 😊I rephrased some points, add few, remove few and added fresh screens from GitHub.
Pull Request = PR
This tutorial is written both for:
- person who create PR, lets call that person creator 👩💻👨💻
- person who reviews PR, lets call that person reviewer 📖
All sections are marked according to which role is making this part.
Table of contents
- What is a Pull Request? 👩💻👨💻/📖
- Creating a Pull Request 👩💻👨💻
- Updating a Pull Request 👩💻👨💻
- Using a Pull Request 📖
- Merging a Pull Request 👩💻👨💻
- Closing a Pull Request 👩💻👨💻/📖
- More
What is a Pull Request? 👩💻👨💻/📖
From Github’s Using Pull Requests Page
Pull requests let you tell others about changes you’ve pushed to a GitHub repository. Once a pull request is sent, interested parties can review the set of changes, discuss potential modifications, and even push follow-up commits if necessary.
Pull Requests are commonly used by teams and organizations collaborating using the Shared Repository Model, where everyone shares a single repository and topic branches are used to develop features and isolate changes. Many open source projects on Github use pull requests to manage changes from contributors as they are useful in providing a way to notify project maintainers about changes one has made and in initiating code review and general discussion about a set of changes before being merged into the main branch.
Here’s an example pull request from jQuery’s github repo.
Creating a Pull Request 👩💻👨💻
There are 2 main work flows when dealing with pull requests:
- Pull Request from a branch within a repository
Pull Request from a forked repository(this article is not about this flow)
Here we are going to focus on 1.
👉 PR from this example: https://github.com/michalczukm/pull-request-tutorial-for-students/pull/1
Creating a Topical Branch
First, we will need to create a branch from the latest commit on master (or develop, depends on git flow you’re using).
Make sure your repository is up to date first using
git pull origin master
Note: git pull does a git fetch followed by a git merge to update the local repo with the remote repo. For a more detailed explanation, see this stackoverflow post.
To create a branch, use git checkout -b <new-branch-name> [<base-branch-name>], where base-branch-name is optional and defaults to master. I’m going to create a new branch called pull-request-demo from the master branch and push it to github.
git checkout -b pull-request-demo
git push origin pull-request-demo
Creating a Pull Request
To create a pull request, you must have changes committed to your new branch.
Go to the repository page on github. And click on “Pull Request” button in the repo header.
Select branches:
- Select the base branch (it is your target branch), where you want to merge your changes to.
- Select compare branch, your branch which you’d like to merge
Enter meaningful title and description for your pull request (other people will be reading this, not machines!).
Remember you can use Github Flavored Markdown in the description and comments.
Finally, click on the green “Create pull request” button to finish creating the pull request.
You should now see an open pull request.
Which might be ready for merge (doesn’t make sense, without code review :exclamation: No way :exclamation:) - depending on your GitHub repository settings.
Or with constraints, like Review reqired (thats how we do it :blush:)
Great :clap:
Now its time for reviewers 📖 to take a look at your PR. I hope you already added them - to they get notified!
From now on this PR is your platform for communication about this code changes.
You can:
- write comments
- answer to other comments
- update PR by adding changes (see👇)
Updating a Pull Request 👩💻👨💻
:wave: you, PR creator, yes you :exclamation:
Since pull request is a request to add commit from one stream (branch) to another, the simplest way to update code in your PR is to … push new commits on your branch.
# add changes, improvements, make your PR better
...
# then commit it
git commit -m "meaningful message describing your changes"
# and push it
git push origin pull-request-demo
Using a Pull Request 📖
So, you received a PR. What next :question:
- View all the commits by all contained by a pull request under the commits tab,
- See all file changed, and make inline comments there (recommended). You
- Review changes/Finish review
After that 👇
Merging a Pull Request 👩💻👨💻
Once you and your collaborators are happy with the changes, you start to merge the changes back to master. There are a few ways to do this.
First, you can use github’s “Merge pull request” button at the bottom of your pull request to merge your changes. This is only available when github can detect that there will be no merge conflicts with the base branch. If all goes well, you just have to add a commit message and click on “Confirm Merge” to merge the changes.
Then confirm it
And done :clap: :clap: :clap:
You can now remove your branch from GitHub. You probably won’t gonna need it since all its changes got merged into master.
Closing a Pull Request 👩💻👨💻/📖
You can always close PR.
👉 PR from this example: https://github.com/michalczukm/pull-request-tutorial-for-students/pull/2
Why?
- it was created by mistake
- it is totally not ready for review
- it is :suspect: and you don’t want it in your repo
- … whatever reason is good for closing it
:warning: If it is your teammate PR, you should probably contact with him/her and discuss that to avoid misunderstandings.
In general - be verbose, be good communicator, ask :blush:
How?
