Coding and Workflow

So you are ready to start making changes to WeBWorK. The first thing you have to decide before you write your first line of code is where do you want your code to end up. There are (usually) three possibilities, as described at Branching and Release Model:

• master: Only small important changes (i.e. hotfixes) should be submitted to master. These are fixes to major bugs.
• release/x.y: This branch is the beta of the upcoming release. Submissions to this branch should either be bugfixing or minor improvements with little risk.
• develop: This is the man development branch. Most submissions should go here.

After you have decided where you want your changes to end up you should create a feature branch as follows:

git checkout -b <my-feature-branch> origin/develop

This feature branch is set up to track, and eventually be merged into upstream/develop. (Of course change develop to whichever branch you are targeting.)

Note: If you just want to check out a version of develop to test something use git checkout origin/develop. This creates a "headless" branch of develop for testing purposes. If you decide you want to keep those changes you can use git checkout -b <my-feature-branch> and it will save your changes to a new feature branch.

Now you are ready to code. The recommended workflow looks something like

1. git checkout -b <my-feature-branch> origin/develop
2. code
3. git commit -a
4. git pull origin/develop
5. fix merge conflicts, if any, and commit changes
6. git push personal <my-feature-branch>
7. repeat

In particular you should be wary about pulling anything other than the tracking branch (e.g. origin/develop) into your feature branch. Ideally after your code is pulled into openwebwork its network graph should either be a "loop" or a "ladder".

origin/develop ----------------------------o
                           \              /
                            \            /
personal/my-feature-branch   o-----o----o

origin/develop ---------------o--o---------o-o-------------o
                           \          \         \         /
                            \          \         \       /
personal/my-feature-branch   o-----o----o--o------o--o--o

Here the last diagonal line represents the final merge of the feature branch into the target branch.

The most strict version of this policy is that your feature branch is only allowed to pull its tracking branch. It should not have any other branches merged into it and it should not be merged into other branches. This is more restrictive than is absolutely necessary, but it is very safe. If you do decide to merge your branch into something else, or merge something else into it, keep the following in mind:

• If you merge a branch from origin other than your tracking branch into your feature branch, then your feature branch will not be able to be merged into openwebwork anymore. I.E. If you based your feature branch off origin/develop then you cannot pull origin/master or origin/release/x.y into your feature branch.
• If you merge another feature branch which is tracking a branch different than your current feature branch, then your feature branch will not be able to be integrated into openwebwork anymore. I.E. If you have feature-a which is tracking origin/develop then you cannot pull feature-b into feature-a if feature-b is tracking origin/master.
• You can merge two feature branches which are both tracking the same branch in origin, but it makes life more difficult for the person evaluating the pull request, so have a good reason for doing so.

Keeping all of your changes in their own feature branches helps keep different features and different changes separate. You can work on your experimental new student view in one branch, bugfix a previous contribution in another branch, and apply a quick hotfix to master in a third. This does mean your local machine fills up with feature branches, though. You can delete branches that have already been merged with git branch -d <my-feature-branch>.