Final deliverable: Packaging
- Due Dec 6, 2024 by 11:59pm
- Points 1
- Available until Dec 23, 2024 at 11:59pm
This checkpoint is to make sure your work is readily accessible to others who want to use it.
How it will work
You will "package" your work as described below (depending on whether it's an element or not), and another team will try to use it to create an example question. Their experience doing this will inform the documentation that ultimately gets packaged with your element.
Using the following arbitrary list of teams, team N will have their work tested by team (N+1) mod numberOfTeams.
Team N should make a pull request from their development branch to the master branch, and assign all members of team N+1 as Reviewers. The Reviewers will review the PR as below, marking any comments that must be addressed before the code can be merged into the master branch of the "golden" repo. Once team N makes the adjustments, team N+1 reviews again, until they are satisfied the PR meets the following criteria.
If the project takes the form of an element
- Make sure all element files are self-contained in a single subdirectory under the
elements/
directory of thepl-ucb-star-assessments
"course" repo on GitHub. If there are external dependencies (other than a Docker image) that do not belong in this directory, let's talk about it so we can figure out how best to package your work! We will be making these available to other courses via advertising mechanisms to be determined. - At the top level of your elements subdirectory, include a README.md that has clear instructions for using the element, including some code for an example question (i.e. an excerpt that might appear in
question.html
) and a screenshot of the result. - Within the
questions
subdirectory for your project, add one or more example questions to which the README refers. - In the README, include a link to your project's "in progress slide deck" used throughout the semester, on Google Drive.
- If your element/questions also require a separate Docker image (e.g. for a custom autograder that doesn't run inside PL itself), please include the Dockerfile with your element code, and send Armando a link to your Docker image: we have a Dockerhub account for the ACE Lab where we can host it and make it readily available. Please also include an example
info.json
file that shows how to reference it at autograding time. - If your element relies on other specific files being available in clientFilesQuestion or serverFilesQuestion, or in clientFilesCourse or serverFilesCourse, make sure the README explains that. Basically, given the README and one of the example questions, an instructor should be able to develop and deploy (view) a similar example question by modifying just the files referred to in the README (question.html, and possibly server.py).
If the project isn't a new element
If your project takes the form of one or more new questions, the in subdirectory under questions
for your project, include one or more example questions (question.html
, and if appropriate, an annotated server.py
) that are explained in a README at the top level. Indicate clearly how instructors should create additional questions: what parts of your example question.html
and/or server.py
files will they need to modify?
For both types of projects
- Make sure that any additional obsolete, unnecessary files that aren't part of the element, documentation, or example questions/assessments are not included in the pull request.
- Make sure the names of files are indicative. For example, "new_question_1" or "question1_copy" are terrible names for question subdirectories. "bfs_example_1" and "bfs_partial_credit_example" are much more descriptive.
- Make sure the README is clearly, concisely, and correctly written. This is the documentation that will be public-facing and will be seen by professors, students, and TAs. If you're not confident of your writing, seek additional assistance. Judicious use of automated tools for grammar checking, style, and rewriting is definitely encouraged.
- For each question you contribute, please include one or more screenshots showing a typical instantiation of the question. Specifically:
- Please try to include only the part of the screen rendering the question, not any of the PrairieLearn gingerbread (navbars, etc.)
- Please make the aspect ratio square if at all possible. (width == height)
- Please make it a PNG file (not GIF, JPG, SVG, etc.)
- Please place the screenshot(s) at the top level of the question's directory (i.e. in the same directory as `info.json`) and name them
screenshot0.png, screenshot1.png
, etc.
"Peer review" for reproducibility
Using only the documentation provided by the authoring team, the reviewing team’s job is to write a functioning question using the authoring team’s code, whether that code takes the form of a PrairieLearn element, a specific set of instructions for writing a question without the use of a new element, or whatever. Please carefully follow the guidelines and timeline outlined below:
- Pairing Up: Each authoring team will be paired with a team reviewing team.
- Authoring a Question: The reviewing team must successfully author a nontrivial question using the authoring team's code and documentation. If the instructions don’t suffice to do this, the reviewing team should give feedback to the authoring team who must then fix the documentation. Repeat this step until the documentation clearly outlines everything that must be done to author questions using the code. It's up to the authoring and reviewing teams to decide how such proposed changes should be communicated and implemented.
- Documenting the Review: Any additional suggestions for improvement (i.e. future work) should become part of the README.md for the element/questions/etc.