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.

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

+

=== Directions (for students): ===

'''Step 1. Create an account'''

'''Step 1. Create an account'''

Revision as of 20:56, 15 August 2016

Title

Working with GitHub Issues, Forks, and Pull Requests

Overview

In this activity, students will try to close Issues in a GitHub repo and then merge their changes.

Prerequisite Knowledge

Students are expected to have GitHub accounts and have a basic understanding of GitHub commits and pull requests.

Contents

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 (or similar):

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.

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.

Criteria

Level 1 (fail)

Level 2 (pass)

Level 3 (good)

Level 4 (exceptional)

Criterion 1...

Criterion 2...

Comments/Notes to Instructors:

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:

ACM Knowledge Area/Knowledge Unit

What ACM Computing Curricula 2013 knowledge area and units does this activity cover? ACM_Body_of_Knowledge