Extended gradetools capability: Assignments on GitHub

library(gradetools)

For this vignette we assume that you have already familiarized yourself with the basic functionalities of gradetools (see the vignette “how-to-grade-with-gradetools”). assist_grading() and assist_team_grading() are essentially wrappers for assist_advanced_grading(), so all functionalities available in those functions are also available in this function.

Here we illustrate gradetools’s functionalities specific to classes that are managed using GitHub organizations. These extended functionalities involve:

• feedback: pushing personalized feedback files to students’ (or teams’) repositories (repo)
• GitHub issues:
  1. taking note of what issues the grader would like to create in a student’s (or team’s) repo;
  2. creating the requested GitHub issues in students’ (or teams’) repos and assigning them to the student (or to team members).

If you would like to see an introduction on how to structure your class on GitHub you can look at the vignette of the ghclass package.

If you have never used ghclass before you will need to set up a GitHub personal access tokens for authentication with GitHub. Refer to the ghclass vignette for instructions.

Cloning assignments from GitHub with ghclass

Before using gradetools functionalities, the user needs to clone from GitHub all the repos where students have pushed their assignments. This can be done easily and quickly using the function local_repo_clone() from the ghclass package.

The code below shows how to clone from the GitHub organization gradetools-test-course all the repos whose name contains week09-regression-. The repos are pulled into a local folder week09-regression that we have created in the folder students-repos in our current working directory.

class_github_name <- "gradetools-test-course"
repo_template_name <- "week09-regression-"
repos_local_path <- "students-repos/week09-regression"

ghclass::local_repo_clone(
  repo = ghclass::org_repos(class_github_name, repo_template_name),
  local_path = repos_local_path
)

A message will be shown to confirm which repos have been cloned (bottom-left screenshot) and the cloned repos will appear in the path specified (bottom-right screenshot).

Taking note of GitHub issues with assist_advanced_grading()

While we are grading, gradetools can give us the option to take note of some GitHub issues that we would like to create in students’ or teams’ GitHub repos. To be given this option, we need to grade using assist_advanced_grading() with the input github_issues set to TRUE.
Noting and pushing issues are separated across two functions. While grading a user can make note of issues and gradetools stores this information to be easily pushed later using push_to_github(). First we will take note of an issue while grading.

The function call below assumes the working directory is a directory with 4 cloned repositories from the gradetools -test-course organization on GitHub:

- quizzes-collected-week09-regression
- week09-regression-federicazoe
- week09-regression-CatalinaMedina
- week09-regression-mdogucu

Both assist_advanced_grading() and assist_team_grading() allow for the creation of GitHub issues. These functions have similar arguments except the second uses team identifiers instead of just student identifiers. Here we will work with assist_advanced_grading() and the same assignments from the “how-to-grade-with-gradetools” vignette. Run the following code to begin.

assist_advanced_grading(
  rubric_path = "quizzes-collected-week09-regression/example-directory-week09-regression/quiz-09-lin-reg-rubric.csv",
  roster_path = "quizzes-collected-week09-regression/example-directory-week09-regression/class-roster.csv",
  grading_progress_log_path  = "quiz-09-lin-reg-grading_progress_log.csv",
  final_grade_sheet_path = "quiz-09-lin-reg-final-grade-sheet.csv",
  example_assignment_path = "week09-regression-CatalinaMedina/quiz-09a-lin-reg-CatalinaMedina.Rmd",
  example_feedback_path = "week09-regression-CatalinaMedina/quiz-09a-lin-reg-CatalinaMedina-feedback.html",
  example_student_identifier = "CatalinaMedina",
  github_issues = TRUE
)

Note the new prompt code “i” for taking note of a GitHub issue while grading.

Grading is not the objective of this vignette, so assign whichever rubric items you would like and stop before grading Mine’s question 3a.

Recall in the “Grading with gradetools” vignette when we wrote a message in Mine’s feedback for the question she forgot to answer. Our message told Mine she could do the question for partial credit. If the assignment was submitted through GitHub creating an issue may be a more immediate way to convey this information.

Use prompt code “i” to note an issue with the title “Answer question for partial credit”, and the body “This question was unanswered. You may complete this question and resubmit your assignment for partial credit.”

Once the issue details have been noted we can use “s” to stop grading at any point to proceed to push the issue to GitHub.

Pushing feedback files and issues to GitHub with push_to_github()

After creation of feedback files and or noting of GitHub issue details, the push_to_github() function allows us to push what we want to GitHub.

Here is what a call to push_to_github() could look like to push feedback files:

push_to_github (
  grading_progress_log_path =  "quiz-09-lin-reg-grading_progress_log.csv",
  class_github_name = "gradetools-test-course",
  example_github_repo = "week09-regression-federicazoe",
  example_identifier = "federicazoe",
  push_feedback = TRUE
)

Here is a description of the specified inputs that are new to us:

• class_github_name is the name of the GitHub organization corresponding to this class;
• example_github_repo is an example of a name of a student’s (or a team’s) repository for this assignment;
• example_identifier is a student_identifier (or team_identifier) from the class roster. For compatibility with GitHub the identifiers need to be student identifiers
• push_feedback = TRUE asks the function to push the feedback files (the same function could be used to only create issues, see below).

To push issues the additional argument would be setting push_issues to TRUE. The two push arguments can be set to true on the same function call.

Running the above function call will push each feedback file to the respective repo, if the repo is found:

Credits

The extended functionalities for assignments managed using GitHub were possible thanks to the functions in the ghclass package.