Git: GitHub Issues and Pull Requests

From Foss2Serve
(Difference between revisions)
Jump to: navigation, search
(Directions:)
 
(22 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{| border="1"
+
__NOTOC__
|-
+
 
|'''Title''' || Name of the activity
+
{{Learning Activity Overview
|-
+
|title=
|'''Overview''' || High level description of what the student will do
+
Working with GitHub Issues, Forks, and Pull Requests
|-
+
|overview=
|'''Prerequisite Knowledge''' || What topics and tools does the student need to know prior to beginning this activity?
+
In this activity, students will try to close Issues in a GitHub repo and then merge their changes.
|-
+
|prerequisites=
|'''Learning Objectives''' || What should the student be able to do after completing this activity?
+
Students are expected to have GitHub accounts and have a basic understanding of GitHub commits and pull requests.
|}
+
 
 +
It is assumed that students have completed these Learning Activities (or similar):
 +
* [[Intro to IRC (Activity)]]
 +
* [[Intro to GitHub (Activity)]]
 +
|objectives=
 +
|process skills=
 +
}}
 +
 
 +
=== 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.
  
=== Background: ===
+
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.
Is there background reading material?
+
  
Are there other activities the student should have done first?
+
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.
  
What is the rationale for this 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.
  
Include helpful hints to faculty here.
+
=== Directions (for students) ===
  
=== Directions: ===
 
 
'''Step 1. Create an account'''
 
'''Step 1. Create an account'''
  
If you do not already have an account, create one at github.com.
+
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/
 
Also be sure that you have git on your local computer or have GitHub Desktop: https://desktop.github.com/
Line 28: Line 36:
 
'''Step 2. Fork and clone repo'''
 
'''Step 2. Fork and clone repo'''
  
Make a fork of the repo at https://github.com/cis-upenn/fun-with-github into your account, then clone it onto your local computer.
+
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'''
 
'''Step 3. Claim an issue to work on'''
Line 52: Line 60:
 
'''Step 6. Submit a Pull Request'''
 
'''Step 6. Submit a Pull Request'''
  
Create a new Pull Request (PR) in the https://github.com/cis-upenn/fun-with-github repo from your fork.
+
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.
 
Then add a comment in the Issue that you claimed, indicating that you have submitted a PR. Include a link to the PR.
Line 62: Line 70:
 
Only when your PR is merged can you consider this step "done," so don't celebrate just yet!
 
Only when your PR is merged can you consider this step "done," so don't celebrate just yet!
  
=== Deliverables: ===
+
=== Deliverables ===
What will the student hand in?
+
 
 +
* ''What will the student hand in?''
  
 
=== Assessment: ===
 
=== Assessment: ===
How will the activity be graded?
 
 
How will learning will be measured?
 
  
Include sample assessment questions/rubrics.
+
* ''How will the activity be graded?''
 +
* ''How will learning will be measured?''
 +
* ''Include sample assessment questions/rubrics.''
  
 
{| border="1" class="wikitable"
 
{| border="1" class="wikitable"
Line 94: Line 102:
 
|}
 
|}
  
=== Comments: ===
+
=== Comments/Notes to Instructors ===
What should the instructor know before using this activity?
+
  
What are some likely difficulties that an instructor may encounter using this activity?
+
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: ===
 
=== Additional Information: ===
{| border="1"
 
|-
 
|'''ACM Knowledge Area/Knowledge Unit''' || What ACM Computing Curricula 2013 knowledge area and units does this activity cover? [[ACM_Body_of_Knowledge]]
 
|-
 
|'''ACM Topic''' || What specific topics are addressed? The Computing Curriucula 2013 provides a list of topics - https://www.acm.org/education/CS2013-final-report.pdf
 
|-
 
|'''Level of Difficulty''' || Is this activity easy, medium or challenging?
 
|-
 
|'''Estimated Time to Completion''' ||  How long should it take for the student to complete the activity?
 
|-
 
|'''Materials/Environment''' || What does the student need?  Internet access, IRC client, Git Hub account, LINUX machine, etc.?
 
|-
 
|'''Author(s)''' || Who wrote this activity?
 
|-
 
|'''Source''' || Is there another activity on which this activity is based?  If so, please provide a link to the original resource.
 
|-
 
|'''License''' || Under which license is this material made available? (http://creativecommons.org/licenses/)
 
|}
 
  
=== Suggestions for Open Source Community: ===
+
{{Learning Activity Info
Suggestions for an open source community member who is working in conjunction with the instructor.
+
|acm unit=
 +
|acm topic=
 +
|difficulty=
 +
|time=
 +
|environment=
 +
Internet access, IRC client, Git Hub account, LINUX machine, etc.?
 +
|author=
 +
[[User:Cmurphy|Chris Murphy]]
 +
|source=
 +
|license=
 +
{{License CC BY SA}}
 +
}}
  
--------------------
+
=== Suggestions for Open Source Community ===
This work is licensed under a
+
[http://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 International License]
+
  
[[File:CC_license.png]]
+
''Suggestions for an open source community member who is working in conjunction with the instructor.''
  
[[Category: Learning_Activity]]
+
[[Category:Learning Activity]]
 +
[[Category:Git]]
 +
[[Category:Work in Progress]]
 +
[[Category:Good Draft]]

Latest revision as of 14:45, 8 September 2018


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.

Prerequisites

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

It is assumed that students have completed these Learning Activities (or similar):

Learning
Objectives
After successfully completing this activity, the learner should be able to:
Process Skills
Practiced


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.

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 (for students)

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.
Criteria Level 1 (fail) Level 2 (pass) Level 3 (good) Level 4 (exceptional)
Criterion 1...
Criterion 2...

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:

ACM BoK
Area & Unit(s)
ACM BoK
Topic(s)
Difficulty
Estimated Time
to Complete
Environment /
Materials

Internet access, IRC client, Git Hub account, LINUX machine, etc.?

Author(s)

Chris Murphy

Source
License

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

CC license.png


Suggestions for Open Source Community

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

Personal tools
Namespaces
Variants
Actions
Events
Learning Resources
HFOSS Projects
Evaluation
Navigation
Toolbox