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

• Video 1 - Next Generation Problem Bank

• Video 2 - Introduction to Prairie Learn

• Video 3 - Authoring questions for Prairie Learn in Markdown

Authoring Questions Details

• Video 1 - Overview of Creating PL problems

• Video 2 - Randomizing and solving physics problem in Python

• Video 3 - Writing a Markdown file for a numerical-entry problem

• Video 4 - Fully implemented numeric entry problem

• Video 5 - Wrting a symbolic PL problem

• Video 6 - Making a multi-part problem

Useful links

• Topics, Subtopics, and Learning Outcomes

• Public version of the OPB

Creating questions on the OPB

Preamble and guidelines

First some general guidelines:

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

1. 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”.

2. You should request reviews from at least two different students on the team.

3. Avoid committing anything to this repository in the output directory; the files in there are automatically generated with scripts in the scripts directory, using the source files.

Instructions

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

2. Change directory into the instructor_physics_bank:

   cd instructor_physics_bank

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

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

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

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

7. 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 do git add -A which 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

   git push.

   Tip

   Here’s a video demo of the authoring process.

8. 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”.

9. When you’re ready to have the problem reviewed by others, convert your Draft PR to an actual PR.

10. Add the syntax check label to trigger an automatic action to check the syntax of your question. Wait for the action to complete.

11. Verify the question looks and works as expected on PrairieLearn.

12. Verify the question looks as expected on the Public version of the OPB.

13. Request one or two reviewers on your problem, wait for their comments and then address them in more commits.

14. Add the ready_to_merge label to mark the question as ready to merge into the OPB after all the conversations have been resolved.

15. Switch back to the main branch locally:

    git switch main

16. Pull any changes (if there are any):

    git pull

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