Invisible Hand is a set of tools to manage your classroom inside github organization. It utilizes Google Sheets , GitHub Classroom and GitHub seamlessly.
pip install invisible-hand
- OSX
brew cask install chromedriver
- Ubuntu
apt install chromium-chromedriver
Invisible Hand operates on 2 config files: github_config.ini and gsheet_config.ini .
Calling hand will automatically propagate these files into working directory with default template. Make sure you have configured them correctly before using them.
Additionally, if you want to use Announce Grade , follow here to get your client secret file and rename it to client_secret.json
The root command
Show Detail Information
append -h or --help options get help messages
$ hand -h
Usage: 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 homeworksinvite users into your github organization
Show Detail Information
hand add-students [github_handle]...Use
-hto see more detailed information about this command.
github_handle: github accounts
hand add-students ianre657 cmprfk1 cmprfk2 cmprfk3- github_config.ini
[github]:personal_access_token[github]:organization[add_students]:default_team_slug
-
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 read access right of TA's group to students' homework repo
Show Detail Information
- github_config.ini:
[grant_read_access]:reader_team_slug: team slug of your TA's group
hand grant-read-access <hw_title>hand grant-read-access hw3Patch to student homework repositories.
Show Detail Information
- github_config.ini:
[github]:personal_access_token[github]:organization
- gsheet_config.ini
[google_spreadsheet]:spreadsheet_url
hand patch-project <hw_title> [--only-repo] <patch_branch>Use
-hto see more detailed information about this command.
Below is the standard workflow to follow.
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 as the 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 disableassignment invitation URLof __hw3__. - Create an PR to your template repo (__
hw3__) by using this command.
hand patch-project hw3 --only-repo="tmpl-hw3" 1-add-some-new-feature
```
6. Accept the PR in your template repository (__ `tmpl-hw3` __). After that, enable the `assignment invitation URL` of `hw3` in GitHub Classroom. Now you have succcessfully updated your template repo.
7. Create PRs to students template repositories ( `hw3-<their github id>` ) by running the scirpt as followed.
``` sh
hand patch-project hw3 1-add-some-new-feature
```
This script would patch to every repository that uses __hw3__ as the prefix under your GitHub organization.
8. 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 (Deprecated)
<img src="./demos/patcher.gif" alt="patcher-demo-video" width="640">
</details>
---
### Crawl Classroom
Crawling homework submission data from Github Classroom
<details><summary><b>Show Detail Information</b></summary>
This is a web crawler for Github Classroom, which is the input of [ `Event Times` ](#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)
<img src="./imgs/clsrm_id.png" alt="id field in the url of github classroom" width="640">
#### Format
``` sh
hand crawl-classroom [OPTIONS] HW_TITLE OUTPUTUse
-hto see more detailed information about this command
hand crawl-classroom --passwd=(cat ~/cred/mypass) hw5 hw5_handle.txtThis example suppose you use Fish Shell and store your password inside
~/cred/mypassUsers should type their passsword inside the pop-up window if they don't provide their password in the argument
- 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
- All students not submitted
- Remember to set deadline of hw on the GitHub classroom (note that deadline can only be set at a future time)
Retrieve information about late submissions
Show Detail Information
Compare the last publish-time of specific git commit in each repository and print out which passed the deadline.
- github_config.ini:
-
[event_times]:deadlinedeadline for homework, in ISO8601 compatible format.For example
2019-11-12 23:59:59(the timezone is set to your local timezone as default).
-
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:hashcould be retrieve fromCrawl Classroom.
__ --deadline __: it will use the variable inside github_config.ini as default.
__ --target-team __ (optional): teams to operate on (use team-slug)
hand event-times --target-team="2020-inservice-students" --deadline="2019-11-12 23:59:59" hw1-handin-0408.txt
Publish feedbacks by creating Issue to student's homework repo.
Show Detail Information
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 Issue s 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 dirand 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 |
- 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)
- Edit config files properly.
- Create feedbacks for students in your
feedback_source_repo - use this script
hand announce-grade <hw_title> [--only-id <student_id>]option:
--only-id : only patch to this student id
hand announce-grade hw3 --only-id 0411276