Creating and maintaining a course repo

tl;dr: Please follow these rules to keep the project manageable as more courses are added:

• A course repo must follow the case-sensitive naming conventions below.

• Access to a course repo must be by creating a child team of pl-dev following the team naming conventions below, and then adding specific individuals to the team. "Generic" GitHub accounts shared unofficially by multiple individuals are not allowed, nor is person-level access. PL admins at UCB will set this up when we first setup your course repo.

---

Repo access

When we create your course repo, we also create a GitHub team named the same way, e.g. for course repo pl-ucb-ee125, we will create the team pl-dev-ucb-ee125. All access to the course repo should be via adding/removing people from that team, not by adding/removing individual access on the repo. Each person must have their own GitHub account---please don't setup a shared GitHub account that many people know the password to---course materials are too sensitive to be handled that way.

Repo structure

Within a course repo, courseInstances/ should contain subdirectories for each offering of the course, beginning with Fa,Sp,or Su plus a 2-digit year, eg Fa20.

questions/ contains all the questions (that is, question generators) used by any instance of the course. Question subdirs should have names that describe the content/topic of the question, not how it is used. E.g. good question name: "html-css-simple-1". Bad name: "Exam1Question4". This template repo contains some interesting questions developed for some of our courses. The pl-example-questions repo also has lots of examples of question generators.

Question subdirs can be nested, so (e.g.) if you have a whole bunch of QGs that address roughly the same topic, you can group them.

Within a course instance, the assessments subdir contains one subdir for each assessment (homework, exam, quiz, lab, anything that looks like a collection of questions) of that course instance. The most important file inside an assessment is the .json file that actually contains the details of the assessment (which questions, grading policy, etc.)

Info for PL admins

You probably don't need to read past this point unless you're part of the team administering PrairieLearn itself.

Creating and configuring course repos

A course is the platonic ideal of a class, e.g. cs61c. Each course has exactly one repo; different offerings (instances) of the course are in a subdirectory of the one repo.

1. On the home page of this repo, click Use This Template, which will create a brand-new repo (not a fork) that starts from a fresh commit history. This will give you the correct basic directory structure, etc. If you're migrating a repo from elsewhere, change its ownership to be in the ace-lab org, change its name to match this naming convention, then follow the remaining instructions for access control.

2. Select ace-lab as the destination of the new repo rather than under your personal account. If you do not do this, your course repo will not be able to be published to the CBT servers.

3. Name the new course repo pl- followed by the university abbreviation (ucb, csulb, ecc) followed by department and course number, e.g. pl-ucb-cs61a, pl-ucb-ee120, etc.

4. Select private as the new repo's visibility, since PL-related repos will necessarily contain sensitive content (future exam questions, etc.)

5. Create a new team pl-dev-university-course, e.g. pl-dev-ucb-cs10, as a child of the team pl-dev (or ask one of the org admins to create it). Grant the new team maintain access on your repo. Add all instructors and student developers for the course to that team. If you don't have the privileges to do this in the org, ask one of the org's owners.

Please do not grant access to repos on a person-by-person basis. Teams make it possible for us to track exactly who has access to which course repos!

6. Also, grant read access to the pseudo-users cbt-DEV-machines and cbt-PROD-machines on your course repo, in order that the courses can be served from Berkeley's PL servers.

Creating the course on the CBT servers (cbt-{dev,prod}`.berkeley.edu}

Ask Finsen Chiu to do the one-time creation of a course on the server and link it to your repo. Subsequent offerings of the course are just different course instances (different subdirs within the courseInstances/ dir of your repo).

IMPORTANT. One person (the course's logical faculty owner) should be given "owner" privileges on the server, and can then add TAs with sub-privileges once that is done. Note that the maintainers of this GitHub org do not have privileges to make these changes on the server, only Finsen can do that.

To allow access to student assessment data (i.e. grades), for example for exporting, an owner can go to the course's Staff tab and add users with specific privileges under the "Student data access" column to view/export student grades or manually change student grades (e.g. when regrades are necessary).