contributing.md

Contributing to PrairieLearn

GitHub: distributed model (for contributors)

Getting started as a collaborator: Everyone should fork the main repository on GitHub. The full name of this repository is PrairieLearn/PrairieLearn ("organization_name/repo_name"); when you fork it, GitHub will create a repo named user_name/PrairieLearn. If you're not sure you 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)

See also the GitHub Help pages on Syncing a fork and Pushing to a remote.

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:

1. Go to the GitHub page for your forked repository.
2. Switch to the branch that you want to merge using the branch dropdown.
3. Click the green compare-and-review button (with two tip-to-tail arrows making a square).
4. 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.

Branches and tags

PrairieLearn version numbers have the format major.minor.patch. Patch-level changes are only for bugfixes.

Branches:

• master - current development branch
• 1.0, 1.1, 2.0 - release branches
• all other branches are for private feature development

Tags:

• 1.0.0, 1.0.1, 1.0.2 - releases on the 1.0 branch, corresponding to prairielearn-1.0.X.tar.gz release tarballs.

Main repository topology:

    *  master branch
    | *  2.1 branch, 2.1.4 tag
    | *  2.1.3 tag
    | *  2.1.2 tag
    | *  2.1.1 tag
    | *  2.1.0 tag
    |/  
    *  2.0.0 tag
    | *  1.2 branch, 1.2.1 tag
    |/  
    *  1.2.0 tag
    | *  1.1 branch, 1.1.1 tag
    | *  1.1.0 tag
    |/  
    *  1.0.0 tag