This TWiki is for technical details only. Any other duty information can be found in Waterloo LEARN (D2L): CS Instructional Support Group -> Course Admin & Duties for ISAs.
CS241e is an enriched version of CS241, but it's quite different from the standard version of the course. This TWiki focuses on the technical side of being an ISA, but if you haven't taken CS241e before, be sure to keep up with the material and stay ahead of students.
Since 2015, CS241e has been consistently taught by one instructor, Ondřej Lhoták. Much of the infrastructure for the course was created by Ondřej and he is always updating and improving it between terms. As such, the information on this TWiki can easily become outdated! IMPORTANT: before running any of the scripts described on this TWiki page, you should read the source code and check that they actually do what you expect. If you notice any incorrect information on the TWiki, please update it.
Ondřej is familiar with Marmoset, and usually he will be the one responsible for creating and maintaining the Marmoset test setups, canonical solutions, and libraries. The ISA will generally not need to do much Marmoset setup. This TWiki page attempts to document all aspects of Marmoset setup for completeness, but this documentation could quickly become incorrect if Ondřej changes his workflow. In general, if there is an issue with the Marmoset scripts, notify Ondřej about it rather than trying to follow the methods on this page.
Note: some of these tasks (such as setting up Piazza, some of the course website updates, updating the assignment code viewer, and creating Marmoset projects) may have already been done by the instructor or previous course staff before you arrived. Information about them is kept here for completeness's sake.
The course email is cs241e@uwaterloo.ca. See the AccessingCourseM365Email page to learn how to access it.
See the AccessingCourseAccount page to learn how to access the cs241e course account.
Note: you'll primarily be accessing the account via SSH during the term.
Note: if you are unfamiliar with Git, see A Brief Overview of Git in this page's Appendix first.
The course Git repository stores course material, which includes:
To clone the course Git repository:
git clone cs241e@linux.student.cs.uwaterloo.ca:private/cs241e.git
See the Create Course Staff File For Current Term section on the CompSci241ISADuties page.
In the course account, there is a script called moss241e.sh in the ~/moss/Scripts/ directory which is used to run MOSS on student submissions.
Read the documentation for the TERM#NUM variables within the script and update them accordingly.
The scripts marm_sql, archive, and moss+archive+update in the ~/bin/ directory are also used to run MOSS on student submissions. Update the CURRENT_TERM variables in archive and moss+archive+update and lines 21 and 23 in marm_sql.
See the Set Up Piazza section on the CompSci241ISADuties page.
The course website is located at https://student.cs.uwaterloo.ca/~cs241e/.
To edit the course website, edit the files in the ~/web/ directory of the course Git repository. Pushed changes will get copied automatically to the ~/public_html/ directory in the course account, where the website is built from. Note: do not edit website files in the course account directly – they will get overwritten after a Git push.
Things to update on the course website:
The course website displays an embedded Google Calendar. Keep it up-to-date throughout the term. It should contain:
Assignment code can be viewed in HTML on the course website at https://www.student.cs.uwaterloo.ca/~cs241e/current/scalasrc/A1.html.
These website pages need to be updated if there is a new version of the assignment code to be used that term.
To update the assignment code HTML viewer:
sbt clean problems
./mkcodehtml
Note: before you can set up Marmoset, CSCF has to create the Marmoset instance for the course and add you with instructor privileges.
See the Adding users sections on the MarmosetSummary page. If you are asked whether or not to limit user ID length, choose to limit it to 8 characters in length.
Note: for the first few weeks of the term, you may have students who enroll into the course late. Watch for emails to the course email account from Waterloo Odyssey regarding changes to the classlist, and add students to Marmoset accordingly.
In CS241e, there is one Marmoset project for each assignment.
To create a project for an assignment, click the "create new project" link on the course's Marmoset homepage. Then fill out the fields as follows:
If you would like to know more details on how Marmoset test scripts are created, uploaded, and executed, see Setting up Marmoset Tests in this page's Appendix.
moss+archive+update
is a relatively new script (Fall 2020) that automates all of the “During The Term” tasks:
Note: the script does not update $moss_folder_paths in check_auth.php, so that will still need to be done manually, as described in the next section.
The script is located at ~/bin/moss+archive+update. To use it, run the following command:
moss+archive+update assignment# [-v] Options: -v: Enables verbose mode
For example, if you are running moss+archive+update on A1, the command would be moss+archive+update 1 [-v].
To run MOSS for an assignment:
marm_sql -d Ax(This will download submissions to ~/handin/Ax/.)
./moss241e.sh AxWhen the command finishes, the MOSS results will be in ~/moss/Ax/ and there will be a subdirectory for each of the previous terms that were compared against.
'Ax' => '/u/cs241e/moss/Ax/html_sc', 'Ax_[term#1]' => '/u/cs241e/moss/Ax/html_sc_[term#1]', 'Ax_[term#2] => '/u/cs241e/moss/Ax/html_sc_[term#2]', 'Ax_[term#3]' => '/u/cs241e/moss/Ax/html_sc_[term#3]',
Students may view their unofficial marks on the course website at: https://www.student.cs.uwaterloo.ca/~cs241e/cgi-bin/displayMarks.py.
The marks shown on the website are read from the file ~/marks/public-marks.txt, stored on the course account.
There is a relatively new script (Fall 2020) called update.sh located in ~/marks/scratch/ which automates the process of updating the official marks.
To update the unofficial marks using update.sh:
./update.sh X
To update the unofficial marks without using update.sh:
marm_sql -v -m AX
./crowdmark.sh midterm-crowdmark.csv > midterm.csv
./combine.sh > public-marks.txt
cp public-marks.txt ..
Note: if the course's late policy for grade calculations has changed for the current term, ~/bin/marm_sql will need to be updated to reflect the changes in how grades are computed.
Note: if the assignments change and/or the number of marks per question have changed for the current term, ~/marks/scratch/combine.sh and ~/marks/scratch/base.txt will probably need to be updated.
Note: CS 241E typically uses only public tests on Marmoset. If release tests or secret tests are ever used, be careful to wait after the late deadline to update the unofficial marks, as updating the unofficial marks prematurely can leak the results of the release/secret tests to students. (It is good practice to wait until after the deadline to update unofficial marks even without release/secret tests anyway.)
Archives for each term are kept in the course account at ~/archives/. A single term's archive contains:
It's suggested to archive MOSS results and original submissions soon after you run MOSS on a given assignment and to archive the assignment pages at the end of the course.
To archive MOSS results:
marm_sql -d Ax
To archive assignment pages:
cp ~/public_html/current/a*.html .
#ABriefOverviewOfGit
You will need a small amount of familiarity with the Git version control system to work as a CS241e ISA. Many Git tutorials jump quickly into subjects like branching, which are extremely important but not really necessary for CS241e. For this reason, we cover a small fragment of Git that should be sufficient for basic tasks like updating the course website.
A Git repository is a collection of files, together with metadata that tracks changes between different versions of the files. The git clone command allows you to create a local copy of the repository on your computer. You can then freely edit the files. The original repository, as well as other people's local copies, will not be affected. When you are satisfied with your changes, the git push command allows you to upload your changes to the original repository. This uploading process doesn't permanently overwrite the files ? a history of versions is maintained using the aforementioned change-tracking metadata. Other users of the repository can use the git pull command to download your changes to their local copy. Because a version history is maintained, if your changes are terrible, people can revert to an earlier version without your changes.
The above paragraph leaves out some steps. Git's change-tracking metadata isn't magic ? you need to tell Git which files it should care about. This is done using the git add command. For example, git add important.txt will tell Git that it should care about the file called important.txt. Often you make changes to a lot of files at once, and using git add =on each one individually would be tedious. In this case, you can use the command =git add -A to add all changed files. There are other options for git add that may be useful in scenarios where you want to add some changed files, but leave others out. You may also find it useful to use a graphical user interface for Git such as SourceTree, which lets you choose which files to add visually.
Once you have added the changed files, you are still not done. You need to tell Git to finalize or "commit" the changes, so that the changes officially get recorded in the version history. This is done with the git commit command. A commit generally includes a short but informative message describing what was changed. The git commit command will open up a text editor in which you can write your commit message. After the commit is finished, you can finally use git push to push your changes to the original repository.
A problem can occur if two people try to make different changes to the same file. A merge conflict occurs if you try to pull changes from the original repository that conflict with the changes in your local copy. Merge conflicts are less scary than many Git beginners think they are, but too scary to explain how to resolve in this little guide. Try to coordinate with other course staff to avoid merge conflicts altogether. If they occur, look for a tutorial on resolving them, or ask for help from someone more experienced with Git.
#TheCourseGitRepository
CS241e currently uses a Git repository to store course material. The term "course material" encompasses:
In the root of the repository, there is a shell script called doall.sh. This shell script runs a number of sbt tasks (sbt is a build tool for Scala) to generate the "problem" and "solution" source code, compile the handout code, run the Marmoset tests against the solutions to check them for correctness, and package the handout code. It also copies the current version of the handout code to the course website's HTML viewer.
You will need to have sbt installed to use the script. If you are working on the school's Linux environment, it should be installed there, but if you are working from your own computer you might have to install it yourself.
The doall.sh script will take a very long time to run because of the fact that it runs all the Marmoset tests. If you just want to generate the "problem" and "solution" source code, you can just run sbt clean problems solutions.
If doall.sh fails, the problem might be differences in the version of Java or the version of some required dependency between your computer and the instructor's computer. Report the problem to the instructor.
An interesting aspect of the course Git repository is that it actually doubles as an IntelliJ project! It works similarly to opening the handout code. Follow the instructions on https://www.student.cs.uwaterloo.ca/~cs241e/current/idea.shtml for opening the handout code in IntelliJ, but instead select the folder containing the Git repository. IntelliJ will create some project metadata files in the Git repository directory, but the repository is actually set up to ignore these extra files, so it shouldn't cause any problems.
This is mostly useful to the instructor for developing the handout code, but it can be a nice way to browse the repository as an ISA. Also, there is one great benefit of this functionality for ISAs: you can use it to run the Marmoset tests directly against student code! This is useful when a student complains about failing a test and has no idea why – you can narrow down the possible reasons by actually running the test case yourself, and give more pointed help.
The idea is to create a second copy of the repository. To test a student's code, download it as a ZIP file from Marmoset, then extract the src directory from the ZIP file to the assignment directory of the copied repository. You can do this using the file marm241test.sh. This will overwrite the assignment code with the student's solutions (which is why we make a copy of the repository). Then, you can run the Marmoset tests (under assignments/test) and they will run against the student's code. When another student asks for help, just replace the previous student's code with the new student's code.
#SettingupMarmosetTests
Initial set-up steps, which only need to be done once.
The workflow is to tweak the tests within IntelliJ IDEA in assignments/test/src/cs241e/, run/debug/test them in IntelliJ, then when you're happy with them, run the mktests.sh script and upload the .jar file for the relevant assignment to Marmoset.
Documentation for potentially useful scripts created in Fall 2020 that are not mentioned earlier on this page.
marm_why is a modified version of the marm_why script from CS 246. It basically mimics the instructor view on Marmoset, minus the web interface.
Given a student ID and assignment name, marm_why creates a directory ~/localtest/[STUDENT_ID].[ASSIGNMENT_NAME]/ containing the test results from each Marmoset test as well as the submitted source code.
marm_why is located at ~/bin/marm_why. To use it, run the following command:
marm_why student_id assignment [-s sub_num] [-t test name] [-v] [-h] Options: -s sub_num: This allows the testing of specific submissions. sub_num should be the submission number seen on Marmoset. -t test: When testing marmoset submission, will only check the specified test instead of checking all of the tests for the submission. -v: Outputs details as the script runs. This can be useful if the script is slow. -h: Display long-form help message
filter_archived_files will "filter" the files of archived student submissions for a given assignment, isolating the specific files that get modified in the course of completing that assignment. The purpose of this is to reduce the total number of files that MOSS checks, since students resubmit their whole codebase for each assignment.
More specifically, for a given assignment, the script will copy over the necessary files for each student from ~/archives/[TERM#]/handin/ to ~/archives/[TERM#]/moss/[ASSIGNMENT]/sc/.
Note: there should typically be no need to run filter_archived_files as, going forward, the archives will be filtered in this manner already. You should only need to run this script if the archives are somehow missing the filtered files or if assignment specifications have changed in your term.
filter_archived_files is located at ~/bin/filter_archived_files. To use it:
filter_archived_files Ax [archived_assignment]
filter_moss_files is located at ~/bin/filter_moss_files. It is used in moss241e.sh to do the file-filtering process on student submissions from the current term. You should not need to run this script directly.
I | Attachment | History | Action | Size | Date | Who | Comment |
---|---|---|---|---|---|---|---|
![]() |
calendar.png | r1 | manage | 4.0 K | 2019-09-04 - 10:42 | SylvieDavies |