WARNING: This documentation may contain unreleased changes. See rubydoc.info/gems/teachers_pet for the version of this README corresponding to the latest release.
Command line tool to help teachers use GitHub in their classrooms.
Each class is an 'organization' on GitHub. This allows the instructors (GitHub organization Owners) to create, push, pull, and administer all repositories. This achieves two goals:
- Instructors can push code starter code to all students
- Instructors can easily browse/pull student code at any time during the assignment to assist in questions, check on progress
Each student is given a team in the organization. The team name is the same as the student's GitHub username. The course instructors are also added as team members for each team (see the goals above).
Install Ruby 1.9.3+, then run
gem install teachers_pet
If you've used this tool before, get the newest version using
gem update teachers_pet
To use the latest-and-greatest code from this repository, see the instructions in CONTRIBUTING.md.
...when using the sandboxing method with private repositories:
-
Create an organization (you will be an owner by default). The organization should reflect the name of your course. See the classroom guide for more info.
-
Have each student/instructor create GitHub accounts.
-
Create a
students
file (you can use an alternate filename and specify with the--students
option if you like)- Individual assignments: one username per line
- Group assignments: one team per line in the format
teamName username username username
-
Add the GitHub username of all instructors to an
Owners.csv
file (one per line) -
Run the following:
teachers_pet create_student_teams ... teachers_pet add_to_team --members Owners.csv ...
teachers_pet create_repos ...
teachers_pet push_files ...
# Multiple times:
teachers_pet open_issue ...
# Then, after the assignment is due,
teachers_pet clone_repos ...
The scripts will ask for your GitHub password in order to run. If you have two factor authentication (2FA) enabled, create a personal access token (replace github.com
with your host for GitHub Enterprise):
Once created, specify the token using the --token
option, or if you add the TEACHERS_PET_GITHUB_TOKEN
environment variable to your .bash_profile
(or equivalent โ example below), it will be picked up by teachers_pet
.
# replace YOUR_TOKEN_HERE below
echo "\n\nexport TEACHERS_PET_GITHUB_TOKEN=YOUR_TOKEN_HERE" >> ~/.bash_profile
source ~/.bash_profile
To learn the options for each action, run
teachers_pet help
# or
teachers_pet help COMMAND
You may need to give other people access to various repositories using teams โ the add_to_team
command can help do this in bulk.
When using the sandboxing setup, you will need to create the repositories for the students. For each assignment, use the create_repos
action to create a repository for each student. The repositories are technically created per team, but if you use create_student_teams
first, then there will be one team per student.
Give collaborator access to everyone who has forked your repository using fork_collab
. Mostly useful for GitHub demonstrations, where the students can quickly be added to a repository without having to worry about collecting usernames.
When creating repositories for students, you will often want to include boilerplate files. After running create_repos
, create a canonical copy of the starter files (e.g. .gitignore
, Makefile
s, etc.) in a repository. From the local clone of the repository, use the push_files
action to place that code in the repositories for each student. This works by creating a Git remote for each student repository, and doing a git push
to each one.
After running create_repos
, instructors can open issues in student repos as a way to list requirements of the assignment, goals, or instructions for patching, using the open_issue
command.
When grading, use the clone_repos
command to clone all the repositories in the organization that match the username-repository naming scheme that is generated when create_repos
is run.