Get PrairieLearn, GitHub, etc. set up

Welcome! Let's get you set up with PrairieLearn. This assignment isn't hard but there's a lot to absorb. This sets the pace for the class.

Feel free to work together or alone, and use the Ed discussion (see left navbar) to post questions/get help (we have no formal GSI, so we want you to help each other!) But each person must submit the final screenshot of their own work.

Note: if you have already developed PrairieLearn questions at Cal, just submit a screenshot of one of the questions you've developed and that satisfies the assignment.

1. Docker & PrairieLearn

You'll need Docker Desktop or some other solution that lets you run Docker containers on your computer. Go find it and install it. Then you can follow the instructions in the "Onboarding - getting started" page of the wiki of the above repo, to install the PrairieLearn Docker image and run it.

Once you have PL running, click the green "Load from disk" button in the upper right corner, which loads one or more PL courses from your local disk. (On the real production server, courses are loaded from copies of repos synced from GitHub.) Open the "QA 101 - Test course" which comes bundled with the PL Docker image. Click Questions to see all the questions associated with this fake course. Pick one and try answering it. Pick another. Play around until you get the basic idea. This is the teacher's view of PL; students would ordinarily only see questions in the context of a specific assessment, as we'll discuss on day one.

Once you've explored the test course(s), it's time to create your own course and an example question.

Stop the running instance of PL (Docker container)...

2. GitHub and course repos

You know GitHub, right? Yes? Good! No? You'll need to be familiar with the basics of repo management, and in particular how to clone a repo to your own computer, how to push your changes back to an origin repo, (most likely) how to collaborate with others using either merges or pull requests (branches are your friend), and other basic stuff. Go ahead, I'll wait here while you inhale all that.

Welcome back. Start by cloning the template repo https://github.com/ace-lab/pl-ucb-csxxx to your own GitHub account, and then git clone your copy of it to your own computer. This repo serves two purposes. First, its wiki (which does not get cloned when you copy the template) serves as some very basic quickstart documentation for the PrairieLearn Links to an external site.assessment authoring system, which all projects will be required to run on, no exceptions. (Hereafter, PL.) Second, its basic structure satisfies the structure of a PL course, and all PL questions must exist inside a course, as you just saw.

You'll create a fake "course" as a receptacle for the question(s) and element(s) you develop in the course project. To do this, modify the "name" and "title" slots in the course information file infoCourse.json in your local copy. Also, modify the uuid of the course. Every kind of PL object—course, question, course instance, assessment, etc.—has a UUID that must be unique in the universe. Generate a new random one using the command line uuidgen in a Unix-like environment, or find a web-based UUID generator, there must be some out there. 

Every time you create any kind of PL artifact by copying/cloning/etc. from an existing template, you must change the UUID of the artifact(s). Do it now before you forget.

OK, no more yelling. The general PL workflow is that you make changes in a local copy of the course repo (in real life or a team project, usually on a branch, but for now you can just make changes on the main branch). Here's how you'll do it:

1. Restart PL (Docker) on your computer, but this time point it at the local copy of the repo you just cloned. The wiki of the original repo explains how to do this. You should see your course's modified name and title appear in PL's home screen, alongside the original "QA 101" and "XC 101" test courses packaged with the PL Docker image.
2. Start a new question by creating a new subdirectory within the questions/ directory of your local course repo. A minimal question has at least two files: info.json (question metadata) and question.html (what the student actually sees). Most nontrivial questions also have other files, especially server.py for autograding. For now, rather than creating these files from scratch, pick a simple question you liked in one of the example courses. Navigate to the Files tab in the navbar, and you can see the files associated with that question. Grab these files' source code and paste them into the corresponding files (info.json, question.html, server.py if it exists) for your new question.
3. In PL, hit the green "Load from disk" button in the upper right corner, which tells PL to reload the whole course from disk, since you have now added/changed a question. Your question should show up in the Questions view of your course in PL.
4. Make a somewhat trivial change to the question—prompt text, wording of choices, or something like that. Also, modify question.html so that your name prominently appears somewhere in the question text. Use "Load from disk" again to reload and verify that your changes are visible in PL.
5. Take a screenshot of PL displaying your modified question, and upload it as your homework submission.
6. Take stock of which files you added/changed (remember git status?) and commit and push the change to your local repo. That's how you work on PL questions: develop locally, Load from Disk to see your changes, and when you're happy, add/commit the right files and push.