Creating and maintaining a course repo

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

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 and grant that 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!

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

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