After the initial expressions exercises, the main way you will be turning in your work is via GitHub pull requests, also known as PRs. PRs let me see how you developed your code, let me leave comments on individual lines of code and the change as a whole, and let you reply with your own comments. Once the code is in a good state you will “merge” it which incorporates it into the main branch of your repository. At the end of the year your portfolio of code will be built from code merged into the main branch of your repository.
Making a pull request
First, write code for the assignment. When you are done, or at a point where you want me to look at your code and give you feedback, click on your GitHub user name at the top right of the screen.
That will take you to your personal repository for this class on GitHub.
You may see a banner telling you that you have changes in a branch that is named for the assignment you are working on with a button to click to make a Pull Request. If so, you can use it. But note, it might be for some different assignment or may not show up at all.
Assuming there's no banner, use the menu shown here to select the branch name that corresponds to the assignment you are working on.
When you select the menu you'll see something like this.
When you select the branch you want, e.g. “assignments/number-functions”, the name of the branch in the menu will change and then you'll see a bar that includes a “Contribute” button. Click it as shown here and then click the big green button that says “Open pull request”.
That will take you to this page. This is your chance to title your PR and leave a comment. For our purposes the default title is probably fine and you do not need to leave any comment though if you have questions that you'd like me to address in my comments, I'd encourage you to ask them here so I see them when I'm looking at your code.
Requesting a review
After you click the “Create pull request” button, your pull request has been created. There is just one last step. Near the top right of the page find the reviewers sections. It looks like this:
Click the gear and then type “gigamonkey” in the text box. Once you start typing it may pop up a menu you can select from.
Then mouse out of the box and the name should show up under the Reviewers list. (The lack of feedback when making this selection is one of the worst aspects of the GitHub UI.) It should look like this:
After you've made a pull request and requested a review you don't have to do anything with it until I've had a chance to review it.
Responding to reviews
When I review your PR I will leave comments on specific lines of code and usually an overall comment.
The first thing you should do is actually read all my comments and make sure you understand them. If you don’t understand something, you can reply with a comment in the PR to ask for clarification or ask me for help during class. This is important because a lot of what I’m going to teach you about programming is going to come in the form of these comments so it’s important that you read and understand them. Also, if I ask a question in a comment you should definitely answer my question in a comment on the PR. (There will be a text box under each comment where you can type a reply.)
What you do after you read the comments depends on what kind of review I’ve left. If I’ve “Approved” the PR you’ll see a block like this near the bottom of the page.
In this case, after reading my comments, you can click the big green “Merge pull request” button and you’re done with the assignment. You should not click that button if I have not approved your PR.
If there are specific changes I want you to make I will leave a “Changes requested” review with comments describing the changes. In that case the block at the bottom will look like:
In this case you should make the requested changes. Sometimes they will be very specific changes in which case making them will probably be easy but I want you to think about why I think they make the code better. Other times the changes may be more general and you’ll have to decide the best way to do what I’ve requested.
To make changes, just edit your code in the normal environment on the Intro to Programming web site. When you run your new code, the changes will be saved to GitHub and added to your PR. Once you have made any requested changes and responded to any comments you should request another review by clicking on the recycle icon in the Reviewers section at the top right of the page:
Doing this will make your PR show up in a list of PRs that I need to review. If you don’t request a new review I’ll assume you’re still working on the code.
A third possibility is that I will just leave some comments, usually when you are in the middle of working on something and I just want to answer some questions you have or to point some things out that will help you as you work on the code. As always, you should read and understand these comments, respond to questions, etc. Then you can continue working and request another review when you’re ready.
Finding your pull requests
From any of the class assignments or assessments you can get to your current PRs by clicking the "PRs" link next to your Github user name.
Or you navigate to your repository and then Click on the “Pull requests” tab near the top of the page:
The number next to “Pull requests” is the number of open pull requests and the default view you will see when you click on the tab is your currently open PRs which are the ones you’ll normally need to deal with. This list of PRs will say whether they are “Approved” or “Changes requested” so you can easily find the ones that are ready to merge and which ones you need to work on more.
A healthy PR list will look something like this. There header tells us there are two open (not merged or otherwise closed) PRs, and one closed PR. The closed PR is not shown in the list but the open ones are. There we can see one “Approved” PR ready to be merged, and one PR that is not labeled either “Approved” or “Changes requested” which is presumably still being worked on.
