Invisible Hand

Invisible Hand is a set of tools to manage your classroom inside github organization. It utilize Google Sheets, Github Classroom and Github seamlessly.

Installation

Install dependencies by using pipenv install && pipenv install -e . and brew cask install chromedriver.

Config Files

Invisible Hand operate on 2 config files : github_config.ini and gsheet_config.ini.

Call invisible-hand will automatically propagate these files into working directory.

Additionally, if you want to use Announce Grade, follow here to get your client secret file and rename it to client_secret.json

Usage

To use the scripts below, you need to activate your python environment by using pipenv shell first.

Invisible Hand

The root command

Show Detail Information

Help Message

append -h or --help options get help messages

$ invisible-hand -h
Usage: invisible-hand [OPTIONS] COMMAND [ARGS]...

    Toolkits for compiler-f19

Options:
    -h, --help         Show this message and exit.

Commands:
    add-students       student_ids: ids to add
    announce-grade     announce student grades to each hw repo
    event-times        repo-hashes : list of <repo>:<hash> strings ex:...
    grant-team-access  Add students into a github team hw-prefix: prefix for...
    patch-project      Patch to student homeworks

Add Students

invite users into your github organization

Show Detail Information

Format

invisible-hand add-students [github_handle]...

Use -h to see more detailed information about this command.

github_handle: github accounts

Example

invisible-hand add-students ianre657 cmprfk1 cmprfk2 cmprfk3

Config file

github_config.ini
- [github]:personal_access_token
- [github]:organization
- [add_students]:default_team_slug

FAQ

Some students report that they didn't get the invitation email.

Invite student into your organization from their email. This should be Github's issue.

about 2 of 80 students got this issue from our previous experience.

Grant specific team read access to H.W. repos

Grant read access right of TA's group to students' homework repo

Show Detail Information

Config File

github_config.ini:
- [grant_read_access]:reader_team_slug: team slug of your TA's group

Format

invisible-hand grant-read-access <hw_title>

Example

invisible-hand grant-read-access hw3

Patch Project

Patch to student homework repositories.

Show Detail Information

Format

invisible-hand patch-project <hw_title> [--only-repo]

Use -h to see more detailed information about this command.

Below is the standard workflow to follow.

Workflow

take homework : hw3(the title of your homework in github classroom) for example:

The repo tmpl-hw3 would be your template for initializing homeworks.
Create another repo to update your template, let's say: tmpl-hw3-revise
inside tmpl-hw3-revise, create a revision branch 1-add-some-new-feature (whatever you like) and an issuse named match your branch name (in this example, 1-add-some-new-feature), which will be the content of your PR message.
Open github-classroom, choose your assignment (hw3) and disable assignment invitation URL of hw3.
Create PR to your template repo(hw3) by using this command.(your need to edit the patch_branch variable in github_project_patcher.py)
```
invisible-hand patch-project hw3 --only-repo="tmpl-hw3"
```
Accept the PR in your template repository (tmpl-hw3). After that, enable the assignment invitation URL under hw3 in Github Classroom. Now you have succcessfully updated your template repo.
Create PRs to students template repositories (hw3-<thir github id>) by running the scirpt as followed.
```
invisible-hand patch-project hw3
```
This script would patch to every repositories under your github organization which's name contains hw3 as prefix.
Merge the revision brnach 1-add-some-new-feature into master in your tmpl-hw3-revise repo. After this step, all documents are updated.

Demo

Crawl Classroom

Crawling homework submission data from Github Classroom

Show Detail Information

This is a web crawler for Github Classroom, which is the input of Event Times

Config File

github_config.ini:
- [crawl_classroom]:login: your login id in Github Classroom
- [crawl_classroom]:classroom_id: the id field of your classroom RESTful page URL. (see the image below)

Format

invisible-hadn crawl-classroom <hw_title> [--passwd] [-o --output]

Use -h to see more detailed information about this command

Example

invisible-hand crawl-classroom --passwd=(cat ~/cred/mypass) -o hw5_handin.txt hw5

This example suppose you use Fish Shell and store your password inside ~/cred/mypass

Users should type their passsword inside the pop-up window if they don't provide their password in the argument

FAQ

ChromeDriver

selenium.common.exceptions.SessionNotCreatedException: Message: session not created: This version of ChromeDriver only supports Chrome version 79

upgrade your chromedriver via brew cask upgrade chromedriver

Demo

Event Times

Retrieve information about late submissions

Show Detail Information

What it actually does

Compare the last publish-time of specific git commit in each repository and print out which passed the deadline.

Config File

github_config.ini:
- [event_times]:deadline deadline for homework, in ISO8601 compatible format.
  
  For example 2019-11-12 23:59:59 (the timezone is set to your local timezone as default).

Format

invisible-hand event-times <input_file> [--deadline="yyyy-mm-dd"]

input-file: file contains list of repo-hash.

repo-hash : in the format of <repo>:<git commit hash>, (for example: hw0-ianre657:cb75e99)

Github API use the first 7 characters of a commit's SHA-1 value to communicate, so the hash we used here is in the length of 7.

The input pairs repo:hash could be retrieve from Crawl Classroom.

--deadline: it will use the variable inside github_config.ini as default.

--target-team (optional): teams to operate on (use team-slug)

Example

invisible-hand event-times  --target-team="2020-inservice-students" --deadline="2019-11-12 23:59:59"  hw1-handin-0408.txt

Demo (need to be updated)

Announce Grade

Publish feedbacks by creating Issue to student's homework repo.

Show Detail Information

Explanation

In every homework project, we would create a git repository for every student. Take homework hw3 with two students Anna and Bella for example, we expect there would be two repos under our github organization, which is hw3-Anna and hw3-Bella. During our grading process, T.A.s would record every grade in a google sheet with a tab named hw3 and a markdown file for each student in every assignment as their feedbacks. After their homeworks being graded, we use this code to publish student's grade by creating Issues named Grade for hw3 to each of their github repositories.

The markdown file for feedbacks contains python template strings, and those strings are the column names inside our google sheet tab hw3. One template string we used is students grades, this makes managing grades more easily.

To use this code, you need to fufill some assumptions.

Lets say you're about to announce the grade for hw3:

prequisite:

a git repo to store student feedback templates, which strutured as followed:

    . Hw-manager # root of your git repo
    ├── hw3
    │   └── reports
    │       ├── 0411276.md
    │       ├── 0856039.md
    │       └── 0956323.md
    └── hw4 # other homework dir

and inside 0411276.md, it would be:

    # Information
    + Student Id: ${student_id}
    + Grade : ${grade}
    # <Some other important things...>
    ...

a google sheet to store student information

student_id grade

0856039 93

0411276 80

student_id	grade
0856039	93
0411276	80

Config file

github_config.ini
- [github]:personal_access_token
- [github]:organization
- [announce_grade]:feedback_source_repo (e.x.: Hw-manager)
gsheet_config.ini
- [google_spreadsheet]:spreadsheet_id
client_secret.json (follow here to download your oauth2 secret file and renamed it to client_secret.json)

instructions to follow

Edit config files properly.
Create feedbacks for students in your feedback_source_repo
use this script

Format

invisible-hand announce-grade <hw_title> [--only-id <student_id>]

option: --only-id: only patch to this student id

Example

invisible-hand announce-grade hw3 --only-id 0411276

Naetw/invisible-hand

Invisible Hand

Installation

Config Files

Usage

Invisible Hand

Help Message

Add Students

Format

Example

Config file

FAQ

Grant specific team read access to H.W. repos

Config File

Format

Example

Patch Project

Format

Workflow

Demo

Crawl Classroom

Config File

Format

Example

FAQ

Demo

Event Times

What it actually does

Config File

Format

Example

Demo (need to be updated)

Announce Grade

Explanation

Config file

instructions to follow

Format

Example