Making a Perfect Pull Request
How to make a perfect pull request so then, it could be bearable for the maintainer to review
What is a pull request?
Pull requests, in their most basic form, are a way for a developer to notify team members that they have completed a feature. Pull requests allow you to inform others about changes you've made to a branch in a GitHub repository. Once a pull request is opened, you can discuss and review potential changes with collaborators and add follow-up commits before your changes are merged into the base branch.
Refer to GitHub docs for a detailed explanation.
Some Visualization Tools (For Beginners)
You can refer these tools while stating out for better visualisation of branches but don't rely on them. CLI is your friend
Unwritten Guide for Pull Requests
Reviewing pull requests is hard
Let's be honest: reviewing pull requests is difficult. It is your responsibility as a reviewer to ensure that the code is correct and of high quality before it is merged into the master. You are expected to do so by examining a diff and a list of files that have changed. You must understand what the pull request is attempting to accomplish, the approach is taken, what's going on, and how all of these files fit together - enough to potentially suggest an improvement. You may need to keep an eye out for typos or stylistic issues. That's a lot of work for a reviewer, especially in a large pull request!
Steps to create PR
- Goto your selected organisation's repo.Once there, click on the Fork button in the top-right corner. This creates a new copy of the repo under your GitHub user account with a URL like:
https://github.com/<YourUserName>/<forked-repo-name>
The copy includes all the code, branches, and commits from the original repo.
Next, clone the repo by opening the terminal on your computer and running the command:
git clone https://github.com/<YourUserName>/<forked-repo-name>
- Once the repo is cloned, you need to do two things:
- Create a new branch by issuing the command:
git checkout -b new_branch
- Create a new remote for the upstream repo with the command:
git remote add upstream https://github.com/<original-repo>
- After making changes in your repo branch
git add .
git commit -m "<your-commit-message--please-write-a-good-one>"
git push -u origin new_branch
Creating a PR
On GitHub.com, navigate to the main page of the repository.
In the "Branch" menu, choose the branch that contains your commits.
Above the list of files, click Pull request.
Use the base branch dropdown menu to select the branch you'd like to merge your changes into, then use the compare branch drop-down menu to choose the topic branch you made your changes in.
Type a title and description for your pull request.
Note: Write desciption and commit messages according to the organization code of conduct
Here we go to some tips
Make smaller pull requests
Write useful descriptions and titles
Add comments on your pull request to help guide the reviewer
Make it visual - Add some screenshots of your changes
Refer my one of the pull requests in zulip
Requesting a pull request review
After submitting a pull request, you can request that a specific person review your proposed changes. If you are a member of the organization, you can also request that a particular team review your changes.
Steps involving requesting the review
Under your repository name, click Pull requests.
In the list of pull requests, click the pull request that you'd like to ask a specific person or a team to review.
Navigate to Reviewers in the right sidebar.
To request a review from a suggested person under Reviewers, next to their username, click Request.
Optionally, to request a review from someone other than a suggested person, click Reviewers, then click on a name in the dropdown menu.
Optionally, if you know the name of the person or team you'd like a review from, click Reviewers, then type the username of the person or the name of the team you're asking to review your changes. Click their team name or username to request a review.
After your pull request is reviewed and you've made the necessary changes, you can ask a reviewer to re-review your pull request. Navigate to Reviewers in the right sidebar and click next to the reviewer's name whose review you'd like.
Note: Steps are sourced from Github Docs