Skip to content

Creating and maintaining a course repo

Jump to bottom
Armando Fox edited this page Jan 19, 2023 · 9 revisions

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.

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!

  1. 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.

  2. Important. Just about every type of thing in PL -- course, question, element, etc. -- has a UUID (Universally Unique ID). You can generate one by typing uuidgen at a Mac terminal or by using the UUID generator. For safety, in the template repo all UUID values have been set to "9999...". In your new repo, immediately git rm any files you do not need, and in the files that remain, replace every UUID with a fresh one.

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.)

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). One person (the course's logical faculty owner) should be given staff 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.

Clone this wiki locally