Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/raul-izquierdo/roster

Helps to update the roster when the students enroll or change groups
https://github.com/raul-izquierdo/roster

github-classroom

Last synced: 4 months ago
JSON representation

Helps to update the roster when the students enroll or change groups

Awesome Lists containing this project

README 

          
# Roster



## Objective



This tool helps you manage your GitHub Classroom roster by identifying students who need to be added, removed, or whose groups have changed, based on a list of enrolled students. Since GitHub does not provide an API for roster management, you must apply these changes manually through the GitHub Classroom web interface.

> **NOTE:** Although this tool can be used **independently**, it is part of a toolkit for managing classes with GitHub Classroom. It is recommended to **first read** the [main repository](https://github.com/raul-izquierdo/classroom-tools) to get an overview of the project and understand how this tool fits in.



## Use Cases



### Creating a Roster



When you first create a classroom, you need to add all your students to the roster. This tool can help you generate the list of students to add.



The required steps are:

- Obtain a list of students enrolled in your course and their lab groups. How you obtain this list depends on your institution. Once you have it, you can provide it to the tool in [various formats](#student-file-formats) (Excel, SIES, CSV, etc.).

- Typically, a teacher does not teach all the groups in a course. Create a group file to filter the output to include only students belonging to the teacher’s groups. Pass the name of this file with the flag `-s`. If that flag is not used, the file name is assumed to be `schedule.csv`. See [Groups File Format](#groups-file-format) for details.



With this information, you can run the tool to generate the list of students to add to your classroom roster. Here are examples with different student file formats:

```bash

java -jar roster.jar create -f sies alumnosMatriculados.xls

```



```bash

java -jar roster.jar create -s mygroups.csv -f excel students.xls

```



```bash

java -jar roster.jar create -s groups.csv -f csv students.txt

```



To avoid having to repeat those arguments in every use of the tool, you can create an `.env` file in the current directory with the name and format of your students file:

```bash

STUDENTS_FILE="alumnosMatriculados.xls"

STUDENTS_FORMAT="sies"

```



Now you can simply run:

```bash

java -jar roster.jar create

```



The output will list the students to add to the roster along with **instructions** on how to do so. For example:



```bash

$ java -jar roster.jar create



## Students to add to the roster

Instructions:

- Go to the Classroom page.

- Click the 'Students' tab.

- Click the 'Add Students' button.

- Select and copy all the lines below at once, then paste them into the 'Create your roster manually' text area.



Izquierdo Castanedo, Raúl (01)

González Pérez, Juan (i02)

...

```



Remember that GitHub Classroom does not provide an API to manage the roster, so you must apply these changes manually through the web interface.



### Updating a Roster



When the semester is underway, students may add or drop the course, or change their lab groups. This tool can help you identify these changes by comparing your current list of enrolled students with the existing classroom roster.



To update an existing roster, you need:

- An **updated** version of the enrolled students.

- The **existing** classroom roster exported from GitHub Classroom. See [Obtaining the Roster file](https://github.com/raul-izquierdo/classroom-tools#obtaining-the-roster-file) for instructions on how to obtain this file. If you keep the name generated by GitHub Classroom, you don't need to specify it, as the default name is `classroom_roster.csv`.



With this information, you can run the tool to generate a list of students to add, remove, or whose groups have changed.

```bash

java -jar roster.jar update -r classroom_roster.csv -s schedule.csv -f sies alumnosMatriculados.xls

```



Or, using the `.env` file mentioned earlier and the default names for the roster and groups files, just run:

```bash

java -jar roster.jar update

```



Example output for the **update** command, which includes instructions to apply the changes manually:



```bash

$ java -jar roster.jar update



## Students to add to the roster



Instructions:

- Go to the Classroom page.

- Click the 'Students' tab.

- Click the 'Update Students' button.

- Select and copy all the lines below at once, then paste them into the 'Create your roster manually' text area.



Izquierdo Castanedo, Raúl (01)

González Pérez, Juan (i02)



## Students to remove from the roster



Instructions:

- Go to the Classroom page.

- Click the 'Students' tab.

- For each of the following lines:

	- Find the student with that roster ID and click the "trash" icon.



Rodríguez, María (01)

Gómez, Ana (i01)



## Students who have changed groups



Instructions:

- Go to the Classroom page.

- Click the 'Students' tab.

- For each of the following lines:

	- Find the student using the old roster ID (shown on the left side of the arrow) and click the "pen" icon.

	- Replace the old roster ID with the new one (shown on the right side of the arrow).



González, Juan (02) ---> González Pérez, Juan (03)

Valles, Pedro (i01) ---> Valle, Pedro (i02)

Ramírez, Lucía (01) ---> Ramírez, Lucía (02)

```



## Usage



The JAR can be downloaded from the [releases page](https://github.com/raul-izquierdo/roster/releases).



Syntax:



```bash

java -jar roster.jar  [OPTIONS] []

```



Commands:

- **create** — prints the students to add to the roster

- **update** — prints students to add, remove, or whose groups have changed since the last roster update



Options:

- **students-file**: The file containing the students.

- **-f **: The format of the students file. Supported: "excel", "csv", "sies". See [Student File Formats](#student-file-formats) for details.

- **-r **: The roster CSV exported from GitHub Classroom (used only with the 'update' command). (default: "classroom_roster.csv"). See [Obtaining the Roster file](https://github.com/raul-izquierdo/classroom-tools#obtaining-the-roster-file) for instructions on how to obtain this file.

- **-s **: A file with the teacher’s groups. (default: "schedule.csv") See [Groups File Format](#groups-file-format) for details.

- **-h, --help**: Show help.



## Student File Formats



The method for obtaining the list of students depends on the institution. To be flexible enough to accommodate different scenarios, this tool supports three student file formats: **sies**, **csv**, and **excel**. The format can be specified with the `-f` option.



### SIES Format



This format is generated by the SIES information system (University of Oviedo). This format is only available for teachers at that university. In this case, the tool is used as follows:



```bash

java -jar roster.jar create -f sies alumnosMatriculados.xls

```



The groups will be created by extracting the group information from the file, removing the prefix and any language indication. For example, the following group names will be transformed as follows:

- "Prácticas de Laboratorio-01" -> "01"

- "Prácticas de Laboratorio-Inglés-02" -> "i02"



### CSV Format



This is a generic format that can be generated from any system. You can create it manually or export it from Excel or any other spreadsheet program.



The CSV file must have two columns (with no header row):

- Student name. There is no required format, but it is recommended to use "Last Name, First Name" to facilitate sorting.

- Group. Likewise, there is no required format, but it is recommended to use a simple format such as "01", "english-02", "i02", etc.



Example:



```csv

"Izquierdo Castanedo, Raúl", group01

"González, Juan", english_group_02

"Alonso, Mariano", group01

"Rodríguez, Javier", group02

```

**NOTE:** Remember to **use quotes** around names that **contain commas** or special characters.



With this file, you can run the tool as follows:



```bash

java -jar roster.jar create -f csv students.csv

```



### Excel Format



This format must be **exactly the same** as the CSV format:

- The first two columns of the Excel file must contain the student name and their group.

- The first row must not be a header row.



To run the tool with an Excel file, use:



```bash

java -jar roster.jar create -f excel students.xls

```



## Groups File Format



This file contains the groups taught by the teacher. If all the groups are taught by the same teacher, simply add all the groups to this file.



The groups file is a simple text file with one group per line. The group names must match those in the students file.



```csv

01

02

i01

```



CSV files with more than one column are allowed, but only the first column is considered. In fact, if `roster.jar` is going to be used along with the rest of the tools in [classroom-tools](https://github.com/raul-izquierdo/classroom-tools), it is recommended to use the same `schedule.csv` file used in the [solutions](https://github.com/raul-izquierdo/solutions#schedule-file-format) tool:



```csv

01, monday, 10:00

02, tuesday, 11:00

i01, wednesday, 12:00

```



Once you have this file, you can use it with both the `create` and `update` commands using the `-s` flag:



```bash

java -jar roster.jar create -s mygroups.txt -f sies alumnosMatriculados.xls

```



If no groups file is provided, the name `schedule.csv` is used by default.



## Exit Codes



The exit codes indicate the result of the command execution:



- **0**: No changes proposed. The roster is up to date.

- **1**: Changes were proposed. The user should review the output and apply the changes manually.

- **2**: An error occurred.



## License



See `LICENSE`.

Copyright (c) 2025 Raul Izquierdo Castanedo