Most engineers manage their repos through PRs. This is how contributors can make suggestions or contributions without committing directly to the main branch, aka the source of all truth. In the ReadMe, you learned how to fork and branch within the GitHub interface. Once you make your changes, you will see a big green button like this:
Click on it, and it will take you to the main repo to commit.
- Write a brief, helpful description of the changes
- Click "Create Pull Request"
- Make note of the PR # / URL for your records, if needed.
Voilà! You've created a PR!
After you create your PR, you'll know when someone has commented or made suggestions through your Notifications. In the top right of your screen, you'll see a little bell icon to the left of your profile picture:
If there's a blue dot next to it, as shown, it means you have unread notifications.
Click on this bell, and it will take you to your Notification page:
Here you see all your notifications. These can be comments on your PRs or others requesting your review on their PR. Click on one to go to review conversations and changes.
Click the check mark to the right, as shown above, when you've addressed that PR. This marks it DONE. Then it disappears from your notifications.
After you click on the PR you'd like to review, it will take to you a page that looks like this:
I've circled the two you'll be using the most: the "Conversation" and the "Files Changed" tabs. Under Conversation, you can read messages directed to you or just follow the conversation between engineers about the contents of that PR. If you have a question for a particular engineer, you can tag them by using @ followed by their username. This notifies them of the tag, but they should also get notifications if there are any changes if they're assigned to the PR, mentioned in it, have been requested to review it, or have commented before.
The "Files Changed" tab shows the comparison between the previous file and the proposed changes.
If you've been asked to review someone else's PR, here is where you make suggested changes.
Mouse over the + signs down the left column until it turns blue, as shown, next to the line you wish to address. You can either leave a normal comment here, asking a question or just making a broad suggestions, or you can click on the icon circled.
That little paper icon with the + inside enables you to make suggested changes. It copies the line in the comment box. Make your suggested changes there. Write any comments or explanation you have about your suggestion beneath those botton three backticks. [```]
To comment on or make suggests for multiple lines, click the blue + and drag it over the lines you wish to address.
Finlly, click on the green "Start a review" button, which saves your comment/suggestions.
There is a final step that's not always noticeable! It's easy to miss!
At the top right, you'll see another green button:
Write a message, as it's good to summarise what you've done.
To submit, you have three choices:
- Comment
- Approve
- Request Changes
The "Comment" option is just that, a comment. No further action needed.
If you choose "Approve," you approve merging the document even if they don't accept your changes or suggestions.
"Request Changes" means those changes/suggestions must be addressed before anyone can merge the PR to the main branch.