# Advanced teaching automation :robot: :mortar_board:

Leverage Renku and Gitlab to automate class management.

## Target audience

This repository is intended for technically inclined teachers who use Renku and/or Gitlab in their class and wish to automate repetitive tasks related to student and project management.

## Purpose

We showcase the potential of Renku + Gitlab through a few scripts covering common use-cases.
These scripts can be used as-provided, but are also meant to be extended and adapted by teachers for their specific needs.

## Content

The following tasks are covered:

* [Inviting students to the class group](#inviting-students-to-the-class-group)
* [Creating student groups](#creating-student-groups)
* [Gathering all forks of a project](#gathering-all-forks-of-a-project)
* [Cloning all forks of a project](#cloning-all-forks-of-a-project)
* [Sending feedback](#sending-feedback)

### Inviting students to the class group

Creating a single group for the class allows to have a centralizd place to store all materials, students repositories and exercises. In some cases, one may also want to make this group private.

The manual process of inviting the whole class to the group can be automated using Gitlab's invitation API. Given a list of student email addresses (e.g. exported from moodle) and the URL to a gitlab group, we provide a script to automatically send an invitation email to each student.

script: [scripts/invite_students.py](scripts/invite_students.py)

usage: `python invite_moodle.py moodle_students_list.csv https://gitlab-instance.com/group-name`


### Creating student groups

When students work on graded assignments, they will usually have to work in private groups. The groups must be accessible to the teachers in order to grade the assignments.

One way to achieve this is to have the teacher create all private student groups (they will therefore be the group owner) and then invite students to their respective groups. We provide a script to automate the group creation and invitation process.

script: [scripts/create_student_groups.py](scripts/create_student_groups.py)

usage: `python create_student_groups.py] students_moodle.csv`

### Gathering all forks of a project

Homework assignment can be provided by the teachers in the form of a repository containing instructions and depencencies required. Students can then fork this project into their own private groups (e.g. created with the script above).

The teacher can then use the Gitlab API to keep track of all student's forks. We provide a script to gather metadata about all student-group forks of a given project, with the option to retrieve the last commit before a deadline. That script will output the metadata as a JSON structure containing the following fields for each fork:

* `id`: The gitlab project ID of the fork
* `url`: The https URL to reach the fork
* `group`: The student group name
* `members`: The members of the group. For each member the following fields are provided:
  + `username`: The gitlab username
  + `name`: The full name (First_name Last_name)
  + `email`: The email address of the student
* `commit`: The hash of the last commit before the deadline, used for grading the assignment.
* `autostart_url`: A URL to directly start a Renku session at the last commit before the deadline.

script: [scripts/collect_forks.py](scripts/collect_forks.py)

usage:

```sh
python collect_forks.py \
  --token token.asc \
  --deadline "YYYY-MM-DDThh-mm-ss" \
  https://gitlab-instance.com/namespace/upstream-project \
  > forks.json
```

### Cloning all forks of a project

In some cases, the student projects may have to be cloned locally by the teacher. We provide a shell script to automate this process. This script will read the JSON output from `collect_forks.py` and clone all the forks at the deadline commit into a target directory.

script: [scripts/clone_forks.sh](scripts/clone_forks.sh)

usage: `python clone_forks.sh forks.json clone_dir`

### Sending feedback

After grading student assignment, the teacher may want to send student groups their grades, as well as positive or critical comments on their solution. This can be automated as well, using the Gitlab issues API. We provide a script to read a csv file containing grades and comments for each student group and open issues in the corresponding repositories automatically.

> TODO