Authoring Markdown questions in PrairieLearn
Contents
Authoring Markdown questions in PrairieLearn#
Welcome to the Open Problem Bank (OPB) in Physics. This repository contains the source code (including solutions) to the questions available publicly here.
Video Resources#
Introduction#
Useful links#
Creating questions on the OPB#
Preamble and guidelines#
First some general guidelines:
We will be using a Branch and Pull Request (PR) method to review contributions to the OPB.
Image credit for the above flow is from GitHub Guides.
Feel free to start a draft pull request while youâre working on the question. When youâre ready, you can click âready for reviewâ.
You should request reviews from at least two different students on the team.
Avoid committing anything to this repository in the
output
directory; the files in there are automatically generated with scripts in thescripts
directory, using thesource
files.
Instructions#
Using the Terminal on your computer, clone this repository locally (i.e. on your computer):
git clone https://github.com/open-resources/instructor_physics_bank.git
Change directory into the
instructor_physics_bank
:cd instructor_physics_bank
Switch to a new branch (replace
newbranchname
with your question number or description):git switch -c newbranchname
(the-c
flag creates a new branch if it does not already exist)Choose a problem that you want to write in markdown, take note of the source, and any attribution you may need to make. Use the Topics, Subtopics, and Learning Outcomes file to get the âTopicâ and âSubtopicâ - you will need to put the question in the correct directory.
Create a subdirectory for the question you want to create inside the
source
directory.Note that the directory structure follows the Topic/Subtopic scheme.
If your question title is âDistance Travelledâ, the equivalent directory name is âdistance_travelledâ and the file containing the questions should be called âdistance_travelled.mdâ.
So the final location of the
distance_travelled.md
should be:source/003.Kinematics(1D)/Position/distance_travelled/distance_travelled.md
Copy one of the question templates from the templates directory into the directory you created in the two steps above. It seems the best way to do this is to copy and paste the file, and then rename it. For our example, that would be the
distance_travelled.md
file.Edit the
distance_travelled.md
file to author your question. Feel free to âcommitâ to the repository as many times as you like. Here are the commands to first add it to the repository, then commit the file, then push it to GitHub:git add source/003.Kinematics(1D)/Position/
(if you are confident you only edited your files, you can also dogit add -A
which adds all files orgit add .
which adds all files in this and its children directories)git commit -m "A message about a change you made
git push
.Open the instructor_physics_bank repo on GitHub.com and create a Draft Pull Request (PR). After you push your branch, you should see a green button called âCompare and Pull Requestâ.
When youâre ready to have the problem reviewed by others, convert your Draft PR to an actual PR.
Add the
syntax check
label to trigger an automatic action to check the syntax of your question. Wait for the action to complete.Verify the question looks and works as expected on PrairieLearn.
Verify the question looks as expected on the Public version of the OPB.
Request one or two reviewers on your problem, wait for their comments and then address them in more commits.
Add the
ready_to_merge
label to mark the question as ready to merge into the OPB after all the conversations have been resolved.Switch back to the
main
branch locally:git switch main
Pull any changes (if there are any):
git pull
Go back to Step 3 to start a new question!
Responding to reviews and making changes#
When a reviewer responds to your pull request and suggests changes, make sure to perform those changes by switching back to this branch by using:
git switch YourBranchName (you donât need the -c because the branch already exists)
After making the changes, perform the git add; git commit -m "fixed comments"; git push
commands once more to push the latest changes to the repository and respond to the reviewer.
More details about the reviewing process can be found here.