Git: GitHub Issues and Pull Requests

Revision as of 20:35, 15 August 2016

Background:

The goal of this activity is to give students experience working with GitHub Issues on a small-scale project, since presumably they will need to do this on their FOSS projects.

They will learn how to claim an Issue in GitHub, fork a repository, push their own changes, issue a Pull Request, and use communication mechanisms such as IRC to collaborate with the rest of the community and make sure their PR is merged.

It is assumed that students have completed these Learning Activities:

• IRC
• Git:_Introduction_to_Github

This activity is meant to be done in a classroom setting, so that everything is happening synchronously in real time. The instructor's role is to act as the repo committer: ensure that contributors are not duplicating effort; check PRs for correctness, adherence to coding conventions, etc.; answer questions about the Issues; merge PRs; mark Issues as closed.

Note that in the activity below, it is assumed that students are working individually and are not allowed to communicate except by IRC (so you will need to set up a channel) and the GitHub Issues comments. You may remove either or both of those restrictions as needed, though it does remove some of the "real-world" aspect of the activity.

Directions:

Step 1. Create an account

If you do not already have an account, create one at http://github.com

Also be sure that you have git on your local computer or have GitHub Desktop: https://desktop.github.com/

Step 2. Fork and clone repo

Make a fork of the repo at (github repo URL) into your account, then clone it onto your local computer.

Step 3. Claim an issue to work on

Go to that repo's "Issues" tab and find one that you would like to work on (some are easier than others!).

/*Is there a way in github to assign this to people?*/

To claim the issue as your own, add a comment indicating that you are working on it. Make sure you aren’t working on the same issue as someone else!

IMPORTANT NOTE! If you would like to communicate with another student or the instructor regarding the issue, you must use the IRC channel and you may not speak until the instructor has said it's okay to do so!

Step 4. Make local changes as needed

Make changes to the code for your issue in your local environment.

This shouldn't take too long but as above, if you need to communicate with another student or the instructor, you must use the IRC channel.

Step 5. Commit/push your changes to your fork

After modifying the code, commit your changes locally and then push them to your fork in GitHub.

Step 6. Submit a Pull Request

Create a new Pull Request (PR) in the (github repo url) repo from your fork.

Then add a comment in the Issue that you claimed, indicating that you have submitted a PR. Include a link to the PR.

Step 7. Wait patiently

Patiently wait in GitHub to see if your PR is merged by one of the repo owners. You may also get a follow-up comment in your Issue, or a note in IRC.

Only when your PR is merged can you consider this step "done," so don't celebrate just yet!

Deliverables:

What will the student hand in?

Assessment:

How will the activity be graded?

How will learning will be measured?

Include sample assessment questions/rubrics.

Comments/Notes to Instructors:

A sample repo with 15 open issues is available at https://github.com/ChrisMurphyOnline/github-issues-activity

This particular repo assumes that students are familiar with Java and JUnit.

Feel free to fork this repo for your own course, but unfortunately I am not aware of ways to clone the issues. I have previously done this by hand (takes about 15 minutes) but there do seem to be scripts to help with this, e.g. https://github.com/IQAndreas/github-issues-import

Here are some notes about the issues in that repo:

• issue #2: in addition to making this change, the student should add a JUnit test. The student should realize this on their own, of course, but if they do not, mention it to them (via the Issue or IRC) and do not merge the PR until a test is added.
• issue #3: the fact that this new method needs a test is referenced in issue #8, so there is something of a constraint here
• issue #5: the conditions that check whether n1 and n2 are 0 are unnecessary. They're not wrong, they're just not needed because of the rest of the method.
• issue #6: clearly the "expected" variable is incorrect. The student can change it, or one of the other variables, but the values must all be negative in this test.
• issue #7: this (intentionally) does not tell the student what the name of the method should be, but it should start with "test" and be related to testing overflow
• issue #8: as noted above, this depends on issue #3 to be implemented
• issue #11: the two testAllDigits methods in DumbStringTest should be changed as a result of this change, though this is not explicitly stated in the Issue. Do not merge the PR until the student has modified the test cases; static methods should be referenced statically, not via an instance object.
• issue #12: although not explicitly stated, the student should modify the javadoc and write a new test case for this method; do not merge the PR until both of these are done
• issue #13: as with #12, this change should also result in a change to the javadoc ("chars" instead of "letters") as well as the test case, which will not compile if not modified
• issue #14: this is more challenging than the others, as the student needs to make sure that letters are not double-counted

Additional Information:

Suggestions for Open Source Community:

Suggestions for an open source community member who is working in conjunction with the instructor.

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License