Skip to content

Latest commit

 

History

History
116 lines (75 loc) · 5.25 KB

upgrading1.md

File metadata and controls

116 lines (75 loc) · 5.25 KB

Upgrading to PrairieLearn v2

The course directory layout for PLv2 is:

exampleCourse
+-- infoCourse.json # needs to be upgraded
+-- questions       # does not change (except for UUIDs)
`-- courseInstances # replaces the 'tests' directory

UUIDs

All JSON configuration files must now contain a UUID (universally unique identifier) to link the on-disk JSON file to the corresponding object in the database (see UUIDs in JSON files for details). In PLv1 this linking was done via the directory name, which meant that directories couldn't be renamed without causing problems. In PLv2 the UUID is used for linking so directories can be freely renamed at any time.

To add a UUID to all the JSON files in a course you can run the included generated_uuids.py Python script, like this:

cd <path_to_PrairieLearn>
cd tools
python generate_uuids.py <path_to_course_directory>

For example, python generate_uuids.py ~/git/pl-tam212.

This script will add a UUID to the start of each JSON file. You will then need to commit and push these changes to GitHub.

When you make new questions, assessments, etc, in the future then you will need to add a UUID to the the JSON file. These can be generated by https://www.uuidgenerator.net (the UUID version doesn't matter).

Upgrading infoCourse.json

Rename courseInfo.json to infoCourse.json.

Delete userRoles from here. It now goes in the infoCourseInstance.json files for each semester.

Make sure assessmentSets, topics, and tags are set according to the new format.

Upgrading the questions directory

No action is needed for the questions directory beyond the UUID addition described above. All questions will continue to work without modification.

Upgrading the tests directory

The tests directory is not used by PLv2. It doesn't matter if it is still present, as PLv2 will just ignore it. The information about tests has now shifted to courseInstances (see below).

The new courseInstances directory

There is a new directory at the top level called courseInstances. The layout of this is:

exampleCourse
`-- courseInstances                      # replaces the 'tests' directory
    +-- Fa16                             # one directory per semester
    |   +-- infoCourseInstance.json      # settings for Fa16 semester
    |   `-- assessments                  # all assessments for the Fa16 semester (equivalent to old tests directory)
    |       +-- hw1
    |       |   `-- infoAssessment.json
    |       `-- hw2
    |           `-- infoAssessment.json
    `-- Sp17                             # another semester
        +-- infoCourseInstance.json
        `-- assessments
            +-- hw1                      # it's ok to reuse assessment names in different semesters
            |   `-- infoAssessment.json
            `-- hw2
                `-- infoAssessment.json

The infoCourseInstance.json files

See the infoCourseInstance.json documentation. One of these files is required inside every semester directory.

The assessments directory

The assessments directory within each course instance is the equivalent of the old tests directory. It contains one subdirectory for each assessment. The word test has been replace by assessment everywhere within PLv2 to be less confusing (assessments include homeworks, or exams, and everything else).

The infoAssessment.json files

See assessment configuration for details on the per-assessment infoAssessment.json files. They are similar to the per-test info.json files from PLv1, but there are some format changes.

testFile replaced with clientFileAssessment (also clientFile)

Files directly within an assessment directory are no longer available to the client. Instead, you should make an clientFilesAssessment directory inside the assessment and put files in this. Within the infoAssessment.json file, replace code like:

<% print(testFile(\"formulas.pdf\")) %>

with:

<%= clientFilesAssessment %>/formulas.pdf

Similarly, <% print(clientFile(\"filename.pdf\")) %> blocks need to be replaced with <%= clientFilesCourse %>/filename.pdf.

See clientFiles and serverFiles for more details.

Renaming clientCode, serverCode, and clientFiles

If you were using them, the following directories at the top course level need to be renamed, and the contents of clientCode and clientFiles should be copied into the single clientFilesCourse directory.

clientCode/*  -> clientFilesCourse/*
clientFiles/* -> clientFilesCourse/*
serverFiles/* -> serverFilesCourse/*

Question code that loads from clientCode/ or serverCode will continue to work without modification, as PrairieLearn will internally map clientCode to clientFilesCourse (and similarly for serverCode).

Any code within clientCode that loads other code from the same directory should load it as ./lib.js, not at clientCode/lib.js.

Rendering LaTeX labels on figures

When using PrairieDraw to dynamically generate figures, the command to generate LaTeX figure labels has changed. See PrairieDraw for details.