iP: Week 4

Suppose you want to propose some changes to a GitHub repo (e.g., samplerepo-pr-practice) as a pull request (PR). Here is a scenario you can try in order to learn how to create PRs:

1. Fork the repo onto your GitHub account.

2. Clone it onto your computer.

3. Commit your changes e.g., add a new file with some contents and commit it.

• Option A - Commit changes to the master branch
• Option B - Commit to a new branch e.g., create a branch named add-intro (remember to switch to the master branch before creating a new branch) and add your commit to it.

4. Push the branch you updated (i.e., master branch or the new branch) to your fork, as explained here.

Pushing a branch to a remote repo

Here's how to push a branch to a remote repo:

Here's how to push a branch named add-intro to your own fork of a repo named samplerepo-pr-practice:

Normally: git push {remote repository} {branch}. Examples:

• git push origin master pushes the master branch to the repo named origin (i.e., the repo you cloned from)
• git push upstream-repo add-intro pushes the add-intro branch to the repo named upstream-repo

If pushing a branch you created locally to the remote for the first time, add the -u flag to get the local branch to track the new upstream branch:
e.g., git push -u origin add-intro

See git-scm.com/docs/git-push for details of the push command.

5. Initiate the PR creation:

1. Go to your fork.

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

3. Set the appropriate 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: master
   

   Normally, the default value shown in the dropdown is what you want but in case your fork has e.g., the repo you forked from is also a fork of a another repo, which means both of those are considered upstream repos of your forkmultiple upstream repos, the default may not be what you want.

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: master
   

6. Verify the proposed code: Verify that the diff view in the page shows the exact change you intend to propose. If it doesn't, commit the new code and push to the branchupdate the branch as necessary.

7. Submit the PR:

The next step of the PR life cycle is the PR review. The members of the repo that received your PR can now review your proposed changes.

• If they like the changes, they can merge the changes to their repo, which also closes the PR automatically.
• If they don't like it at all, they can simply close the PR too i.e., they reject your proposed change.
• In most cases, they will add comments to the PR to suggest further changes. When that happens, GitHub will notify you.

You can update the PR along the way too. Suppose PR reviewers suggested a certain improvement to your proposed code. To update your PR as per the suggestion, you can simply modify the code in your local repo, commit the updated code to the same master branch, and push to your fork as you did earlier. The PR will auto-update accordingly.

Sending PRs using the master branch is less common than sending PRs using separate branches. For example, suppose you wanted to propose two bug fixes that are not related to each other. In that case, it is more appropriate to send two separate PRs so that each fix can be reviewed, refined, and merged independently. But if you send PRs using the master branch only, both fixes (and any other change you do in the master branch) will appear in the PRs you create from it.

To create another PR while the current PR is still under review, create a new branch (remember to switch back to the master branch first), add your new proposed change in that branch, and create a new PR following the steps given above.

It is possible to create PRs within the same repo e.g., you can create a PR from branch feature-x to the master branch, within the same repo. Doing so will allow the code to be reviewed by other developers (using PR review mechanism) before it is merged.

The PR review stage is a dialog between the PR author and members of the repo that received the PR, in order to refine and eventually merge the PR.

Given below are some steps you can follow when reviewing a PR.

1. Locate the PR:

1. Go to the GitHub page of the repo.
2. Click on the Pull requests tab.
3. Click on the PR you want to review.

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

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

4. Add review comments:

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 mark multiple lines, click-and-drag the icon.
2. Enter your comment.
   This page @SE-EDU/guides has some best practices PR reviewers can follow.
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. Repeat the above steps to add more comments.

5. Submit the review:

1. When there are no more comments to add, click on the Review changes button (on the top right of the diff page).
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.
   

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

The PR review stage is a dialog between the PR author and members of the repo that received the PR, in order to refine and eventually merge the PR.

Given below are some steps you can follow when reviewing a PR.

1. Locate the PR:

1. Go to the GitHub page of the repo.
2. Click on the Pull requests tab.
3. Click on the PR you want to review.

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

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

4. Add review comments:

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 mark multiple lines, click-and-drag the icon.
2. Enter your comment.
   This page @SE-EDU/guides has some best practices PR reviewers can follow.
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. Repeat the above steps to add more comments.

5. Submit the review:

1. When there are no more comments to add, click on the Review changes button (on the top right of the diff page).
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.
   

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