Package: repobee-csvgrades
repobee-csvgradesImportant:repobee-csvgrades v0.2.0 and later require RepoBee 3.A plugin for reporting grades into a CSV file based on issue titles.repobee-csvgradesadds therecordcategory to repobee, along with thegradescommand, which operates on the
JSON file produced by runningrepobee list-issueswith the--hook-results-fileoption. The idea is pretty simple: find issues in student
repositories that match certain user-defined conditions (title + who opened it)
and report the corresponding grades into a (preferably version controlled) CSV
file.Example use caseSay that you have three students,slarse,glasseyandglennol, three taskstask-1,task-2andtask-3, and that you (and any colleagues) open issues
with titlesPassfor pass andFailfor fail.repobee-csvgradescan then
be configured to look for issues with those titles (using a regex), and write
them into a grades sheet that looks something like this:name,username,task-1,task-2,task-3
    Simon Larsén,  slarse,     P,     P,     F
 Richard Glassey, glassey,     P,     P,     P
    Glenn Olsson, glennol,     P,     P,     PGitHub and CSV files:GitHubrenders CSV files really nicely,
they are even searchable!Only grades from issues that were opened by authorized teachers, as specified
by you, are written to the file. Grades are mapped from issue title to a
symbol, so the CSV file becomes more readable (here there's for examplePforPass). You also assign grades a priority, so if for example there's both a
fail and a pass issue in a repo, it will pick the one that you've specified is
most important.  Additionally, each time new grades are reported, a summary
message will be produced that looks something like this:Record grades for task-3

@ta_a
slarse task-3 F

@ta_b
glassey task-3 PThe@ta_aand@ta_bare mentions of the teachers/TAs (with usernamesta_aandta_b) that opened the issues. The intention is that this message should be
used as a commit message for the grades file, so that the people who reported
grades get notified of which grades have been written to the grades sheet.That's just a quick introduction, seeUsagefor a more detailed
description.InstallAs ofRepobee 3.0, installing a plugin is easier than ever.First, make sure that you have the latest version ofRepobeeinstalled,
instructions can be found on theRepobee website.To installrepobee-csvgrades, simply run the commandrepobee plugin install, and this will open up a bullet-list where you can select csvgrades.Ifrepobee-csvgradesdoes not show up when running thegrades recordcommand. Runrepobee plugin list, this will present a list with all the availiable plugins. If you cannot findrepobee-csvgradesin the list, try updatingrepobeeusing repobeerepobee manage upgrade.Usagerepobee-csvgradesis easy to use and highly customizable. First of all, you
need to know how to use a plugin for RepoBee, see theRepoBee plugin docs.
Then, there are a few key parts to familiarize yourself with before using it,
however. The following sections explain the command line options in depth. Also
don't miss the fact that you can configure all options in theconfiguration file.The grade specification (--grade-specsoption)The grade specification (orgrade spec) is the most important part of this
plugin. Grade specs tell thegrades recordcommand which issues to consider as
grading issues, and which grading issues outweigh others if several are found. A
typical grade spec looks like this:1:P:[Pp]ass. There are three parts to the
grade spec, delimited by:. First is the priority. A lower priority outweighs
a higher priority. Second is the symbol that is written to the CSV grades file.
Third is a regex to match against issue titles. Any issue whos title matches the
regex is considered a grading issues of that spec.Important:Your grade spec regexes shouldnotoverlap (i.e. be able to
match the same strings). If they do, behavior is undefined.Grade specs are specified by the--grade-specsoption. Example:--grade-specs '1:P:[Pp]ass' '2:F:[Ff]ail' '3:C:[Cc]orrection'The hook results file (--hook-results-fileoption)grades recordoperates on a file with a JSON database produced by theissues listcommand (one of RepoBee's core commands). The file is produced by
supplying the--hook-results-file FILEPATHoption toissues list. You
should additionally supplyissues listwith the--allflag, to get both open
and closed issues (so as to avoid missing grading issues). If you try to usegrades recordwith a hook results file that's been produced without the--allflag, it will exit with an error. If you really want to run with that
file, you can supply the--allow-other-statesflag togrades record, which
disregards how the hook results were collected.The hook results file is specified by the--hook-results-fileoption. Example:--hook-results-file ~/some_course/2019/hook_results_jan.jsonThe grades file (--grades-fileoption)grades recordwrites grades to a CSV file that we refer to as thegrades
file. Each row represents one student, except for the first row which is a
header row. The following requirements are placed on the CSV file format:Commas must be used as the delimiterThe first line of the file must be a row of headersOne of the headers must beusername, and the column must include the
usernames of all students to be gradedThere must be one column for each master repo, and the header for that column
must exactly match the master repo's nameBelow is an example grades file that has been partially filled in by thegrades recordcommand. As it is a CSV file, it is rendered very nicely on
GitHub (see for examplethis test file), and it
is strongly recommended that you keep this file in version control.name,username,task-1,task-2,task-3,task-4,task-5,task-6
    Simon Larsén,  slarse,     P,     P,     F,      ,      ,  
 Richard Glassey, glassey,     P,     P,     P,      ,      ,  
    Glenn Olsson, glennol,     P,     P,     P,      ,      ,There are a few additional things to keep in mind with the grades file.You should not manually edit the file with grade symbols for which there are
no grade specifications, as this may causegrades recordto exit because it
can't find a priority for the grade.You can't have a task calledusername.You can't have duplicate column headers.Youcanhave any additional columns that you want.grades recordwill
only look at theusernamecolumn, and the columns corresponding to the
master repo names that you specify when calling the command. Additional
columns will simply not be inspected.grades recordformats the diff file such that every cell of the same column
has the same width, which makes diffs easy to inspect.Because of this formatting, it is recommended to keep grade spec symbols
shorter than the master repo names, to avoid resizing of columns when grades
are entered.The grades file is specified by the--grades-fileoption. Example:--grades-file ~/some_course/2019/grades.csvThe edit message file (--edit-msg-fileoption)Each time you rungrades record, a file is produced specifying what new grades
were recorded, and tags the teachers who opened the grading issues. The
intention is that this edit message should be used as a Git commit message. For
example, ifslarsehas teacherta_a, andglasseyhas teacherta_b, and
they both got new grades fortask-3, the edit message might look like ths:Record grades for task-3

@ta_a
slarse task-3 F

@ta_b
glassey task-3 PThe reason this edit message file exists is that some of our TAs felt a bit
nervous about not knowing when their reported grades were collected. If this
edit message is posted as the commit message, every teacher/TA whos grades have
been collected will be notified, and the extra thorough ones can even inspect
the diff to make sure everything is OK.The destination for the edit message file is specified by the--edit-msg-fileoption. Example:--edit-msg-file edit_msg.txtAuthorized teachers (--teachersoption)Thegrades recordcommand requires you to specify a set of teachers that are
authorized to open grading issues. This is to avoid having students trick the
system. If an grading issue by an unauthorized user is found, a warning is
emitted. This is both to alert the user about potential attempts at foul play,
but also to help identify teachers that are actually authorized, but have not
been included in the list.Teachers are specified with the--teachersoption. Example:--teachers ta_a ta_bConfiguration file sectionrepobee-csvgradescan fetch information from theRepoBee configuration file,
under thecsvgradessection. All of the command line options can be
configured. Use theconfig wizardcommand to configurecsvgrades.Important:The plugin must be active when runningconfig wizard, or
otherwise it will not be configurable. Here, we activate it with-p csvgrades.$ repobee -p csvgrades config wizard
Editing config file at /home/slarse/.config/repobee/config.ini
Select a section to configure:
 repobee
●csvgrades # make sure to select the csvgrades section to configureNote that some of the configurable options are lists, such as theteachersandgrade-specsoptions. Simply separate each item in the list with a space,
like you would on the commmand line. If an item contains a space (such as a
regex in a grade spec), the whole item must be surrounded with single quotes.Licenserepobee-csvgradesis released under the MIT license. SeeLICENSEfor details.