Thanks for your interest in contributing to PrairieLearn!
If you're making a small enhancement, fixing a typo, or updating some documentation, you can jump ahead without getting any maintainers involved first. Onward!
If you want to make a larger change, such as implementing a new feature, changing an API, or introducing a new element, you should first start a discussion with the maintainers to make sure that your change would ultimately be accepted. This can be in the form of a GitHub issue or discussion, or for really big features, you can open a PR with an RFC. The maintainers will work with you to answer any questions, fill in any gaps, and ensure that your proposed change will integrate well into PrairieLearn.
Before you start contributing, you'll need to fork the repo.
Once you've forked, you'll need to clone your fork and set up your development environment. Depending on your preferred workflow, you can develop inside of a Docker container that has all the dependencies pre-installed, or you can develop "natively" directly on your computer.
You're now ready to start implementing your changes!
The aforementioned setup documentation also includes instructions on starting a server, running tests, and running the linters.
The dev guide is currently quite long and dense, but it contains a lot of information about our preferences, conventions, and code structure.
If you get stuck, reach out to the friendly folks in the #pl-dev channel on the PrairieLearn Slack!
We follow the GitHub flow for all changes:
- You should work on a distinct branch, not
master. While this isn't strictly necessary for forks, it's helpful if you want to be working on multiple independent changes at the same time. - When committing your changes, use a short but meaningful commit message, e.g.
fix rate limitinginstead offix. - Once you're happy with your changes, open a pull request (PR).
- You should include a reasonable amount of information with your pull request, such as a summary of what changes you made and why they were made.
- For changes that impact UI, it can be helpful to include screenshots and screen recordings.
- If applicable, include instructions on how to manually test or verify your change.
- If the change you're making will resolve an existing issue, you should link the issue to the pull request so that the issue is closed automatically once the pull request is merged.
- Monitor the GitHub status checks. If they fail, you should check the output to see why. You may need to fix a broken test, adjust the formatting of your code, or fix a lint error.
- Like many open-source projects, we require you to "sign" a contributor license agreement (CLA) prior to accepting any contributions. When you open your first pull request, a bot will prompt you to leave a comment stating that you accept the terms of our CLA.
- One or more PrairieLearn maintainers will review your PR. You should be prepared to engage with the maintainers to answer questions, update code, etc.
- Once the PR is in a satisfactory state, a maintainer will approve and merge your change! 🎉
After your changes have been merged to master, a new prairielearn/prairielearn Docker image will be built and published to Docker Hub. If you're developing course content locally, you can then run docker pull prairielearn/prairielearn to access the new image.
Usually, your changes will be deployed to all production instances of PrairieLearn within a week. Watch the #announce Slack channel to see when your change has been deployed. If it's been several weeks since your PR has been merged and your changes still haven't been deployed, feel free to reach out in the #pl-dev Slack channel.
Note that the cadence of deploys may be impacted by typical academic calendars. That is, we may deploy fewer changes less often during December or May when final exams are in session.