Authoring Markdown questions in PrairieLearn
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.
Authoring Questions Details#
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
outputdirectory; the files in there are automatically generated with scripts in the
scriptsdirectory, using the
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
Switch to a new branch (replace
newbranchnamewith your question number or description):
git switch -c newbranchname(the
-cflag 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
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
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.mdfile 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 do
git add -Awhich adds all files or
git add .which adds all files in this and its children directories)
git commit -m "A message about a change you made
When you’re ready to have the problem reviewed by others, convert your Draft PR to an actual PR.
syntax checklabel 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.
ready_to_mergelabel to mark the question as ready to merge into the OPB after all the conversations have been resolved.
Switch back to the
git switch main
Pull any changes (if there are any):
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.