Git-Mastery: Lessons

preparation samplerepo-pr-practice is an unmonitored repo that we have created for you to practice working with PRs.

• i.
  Fork that repo onto your GitHub account.
• ii.
  Clone it onto your computer.
• iii.
  Commit some changes (e.g., add a new file with some contents) onto the main branch.
• iv.
  Push the branch you updated (i.e., main branch or the new branch) to your fork, as explained here.

1 Go to your fork on GitHub.

2 Click on the Pull requests tab followed by the New pull request button. This will bring you to the Compare changes page.

3 Specify the target repo and the branch that should receive your PR, using the base repository and base dropdowns. e.g.,
base repository: se-edu/samplerepo-pr-practice base: main

4 Indicate which repo:branch contains your proposed code, using the head repository and compare dropdowns. e.g.,
head repository: myrepo/samplerepo-pr-practice compare: main

5 Verify the proposed code: Verify that the diff view in the page shows the exact change you intend to propose. If it doesn't, as necessary.

6 Submit the PR:

done!

Preparation If you do not have access to a PR that you can review, you can create one for yourself as follows:

• i.
  Create a branch in a repo that you have forked and cloned (e.g., samplerepo-pr-practice).
• ii.
  Do some changes in the branch.
• iii.
  Push the branch to the remote repo.
• iv.
  Create a PR within your fork, from the new branch to the main branch.

1 Locate the PR:

• 1.1)
  Go to the GitHub page of the repo.
• 1.2)
  Click on the Pull requests tab.
• 1.3)
  Click on the PR you want to review.

2Read the PR description. It might contain information relevant to reviewing the PR.

3Click on the Files changed tab to see the diff view.

4Add review comments:

• 4.1)
  Hover over the line you want to comment on and click on the icon that appears on the left margin. That should create a text box for you to enter your comment.

  • To give a comment related to multiple lines, click-and-drag the icon. The result will look like this:
    
• 4.2)
  Enter your comment.
  

  • This page @SE-EDU/guides has some best practices PR reviewers can follow.
  • To suggest an in-line code change, click on this icon:
    
    After that, you can proceed to edit the suggestion code block generated by GitHub (as seen in the screenshot above).
    The comment will look like this to the viewers:
    
    
• 4.3)
  After typing in the comment, click on the Start a review button (not the Add single comment button. This way, your comment is saved but not visible to others yet. It will be visible to others only when you have finished the entire review.
  

• 4.4)
  Repeat the above steps to add more comments.

5Submit the review:

• 5.1)
  When there are no more comments to add, click on the Review changes button (on the top right of the diff page).
• 5.2)
  Type in an overall comment about the PR, if any. e.g.,

  Overall, I found your code easy to read for the most part except a few places
  where the nesting was too deep. I noted a few minor coding standard violations
  too. Some of the classes are getting quite long. Consider splitting into
  smaller classes if that makes sense.
  
      
  
      Copy
      
  
      
  
  
      
      
      
      
  
      Wrap Text
      
  
      
  
  
      
      
      

  LGTM is often used in such overall comments, to indicate Looks good to me (or Looks good to merge).
  nit (as in nit-picking) is another such term, used to indicate minor flaws e.g., LGTM. Just a few nits to fix..
• 5.3)
  Choose Approve, Comment, or Request changes option as appropriate and click on the Submit review button.

done!

Preparation If you would like to try merging a PR yourself, you can create a dummy PR in the following manner.

• i.
  Create a branch in a repo that you have forked and cloned (e.g., samplerepo-pr-practice).
• ii.
  Do some changes in the branch.
• iii.
  Push the branch to the remote repo.
• iv.
  Create a PR within your fork, from the new branch to the main branch.

1 Locate the PR to be merged in your repo's GitHub page.

2 Click on the Conversation tab and scroll to the bottom. You'll see a panel containing the PR status summary.

3 If the PR is not merge-able in the current state, the Merge pull request will not be green. Here are the possible reasons and remedies:

• Problem: The PR code is out-of-date, indicated by the message This branch is out-of-date with the base branch. That means the repo's main branch has been updated since the PR code was last updated.
  • If the PR author has allowed you to update the PR and you have sufficient permissions, GitHub will allow you to update the PR simply by clicking the Update branch on the right side of the 'out-of-date' error message. If that option is not available, post a message in the PR requesting the PR author to update the PR.
• Problem: There are merge conflicts, indicated by the message This branch has conflicts that must be resolved. That means the repo's main branch has been updated since the PR code was last updated, in a way that the PR code conflicts with the current main branch. Those conflicts must be resolved before the PR can be merged.
  • If the conflicts are simple, GitHub might allow you to resolve them using the Web interface.
  • If that option is not available, post a message in the PR requesting the PR author to update the PR.

4 Merge the PR by clicking on the Merge pull request button, followed by the Confirm merge button. You should see a Pull request successfully merged and closed message after the PR is merged.

• You can choose between three merging options by clicking on the down-arrow in the Merge pull request button. If you are new to Git and GitHub, the Create merge commit option is recommended.

done!