Contributing to PrairieLearn
GitHub: distributed model
Getting started as a collaborator: Everyone should fork the main repository on GitHub. The full name of this repository is
"organization_name/repo_name"); when you fork it, GitHub will create a repo named
user_name/PrairieLearn. If you're not sure how to fork the repo, see Github's instructions.
Next, clone your forked repository to your local machine and set up the main repository as an "upstream" repository:
git clone [email protected]:$user_name/PrairieLearn.git git remote add upstream [email protected]:PrairieLearn/PrairieLearn.git
This means that you now have three key repositories to keep track of:
- Upstream: the main PrairieLearn repository on GitHub. You can't directly push to this, but this is where you will pull other people's commits from.
- Origin: your forked repository on GitHub. You can push and pull directly to this.
- Local: your clone of origin on your local computer. This is where you commit before pushing to origin.
Important note: Don't ever commit anything to the
master branch. You should do all your work in branches and issue pull requests from these branches back to the main PrairieLearn repository.
Updating your fork from upstream: Getting new changes from upstream is a two-step process. First you pull from upstream to your local repository, then you push the new changes back to your origin. (There is no direct communication between upstream and your forked origin repository.) Note that for this to work it is critical that you have never committed anything to your master branch. The procedure to pull and then push is:
git checkout master # make sure you are on the master branch git pull upstream master # pull new changes from upstream git push origin master # push the new changes back up to your fork (origin)
Editing, committing, and pushing your code: You should only ever commit and push code on a branch (never on
master). To start a new branch, do:
git checkout -b branch_name
Later, you can do:
git checkout branch_name # make sure you are on the right branch # ... edit code git add "FILE.js" git commit -m "MESSAGE" git push origin branch_name # this should be the same as the branch you checked out
This makes local code changes and then pushes them up to your forked repository (origin). See also Pushing to a remote on the GitHub Help pages.
Merging your code back into upstream and master: You should never merge your branches into your own master. Instead, issue Pull Requests (PRs) to have them merged back into the main PrairieLearn repository. To do this:
- Go to the GitHub page for your forked repository.
- Switch to the branch that you want to merge using the branch dropdown.
- Click the green compare-and-review button (with two tip-to-tail arrows making a square).
- Click the green "Create pull request" button.
Once your code is accepted, you can then get it back into your master by updating your fork from upstream, and then you can delete your branch that was merged. See also Using pull requests on GitHub Help.
Updating the ChangeLog: Before issuing a PR, you should update the file
ChangeLog.md, which we use to maintain an ordered list of changes made to each version of PrairieLearn. Each line in
ChangeLog.md must be one short sentence with this format:
* [Keyword] [description] ([First name] [Last name]).
The keyword must be either
Change. For example:
* Fix broken popovers in input elements (Tim Bretl).
One empty line must separate each item in the ChangeLog. Items should be ordered first by category (
Change) and then chronologically, with the most recent item appearing at the end of each category list.
Branches and tags
PrairieLearn version numbers have the format
major.minor.patch. Patch-level changes are only for bugfixes.
master- current development branch
2.0- release branches
- all other branches are for private feature development
1.0.2- releases on the
1.0branch, corresponding to
Main repository topology:
* master branch | | * 2.1.4 tag, 2.1 branch | * 2.1.3 tag | * 2.1.2 tag | * 2.1.1 tag |/ * 2.1.0 tag | * 2.0.0 tag, 2.0 branch | | * 1.2.1 tag, 1.2 branch |/ * 1.2.0 tag | | * 1.1.1 tag, 1.1 branch | * 1.1.0 tag |/ * 1.0.0 tag
I forgot to branch. How do I move changes from master to a new branch?
No problem, assuming that you have not made any commits yet. First, create and checkout a new branch in which to keep your changes, leaving the current branch as is.
git checkout -b <new-branch>
Then, make a commit as you normally would:
git add <files> git commit -m "<Brief description of this commit>"
Once your commit is made, you can checkout and reset master.