Branching and Release Model

The branching and release model used by WeBWorK is based on the git flow model, and is designed to make it easier to understand the nature of pull requests from the various developers so that they can be reviewed and merged more quickly, while still providing the flexibility to test new features as they are developed. This is especially important because developers need to make a choice about which branch they want their code to end up in before they start coding so that they can base their feature branch off of the right openwebwork branch.

In this model, the master branch always represents the current release, and any commit to this branch marks a new release (either as a hot-fix for the current release, or as a new numbered release). In particular you should only base a working branch off of this branch if you are making a small fix for an important bug. Release pull requests will always be created and handled by maintainers.

There will often be a second branch called release/x.y. This branch contains the beta version of the next WeBWorK release. This branch is created by splitting off of the develop branch and is used for testing and bugfixing purposes. In particular working branches should only be based off of this branch if they are fixing bugs for the upcoming release, or if they add a feature which is either superficial or has little chance of breaking anything. If there is no release/x.y branch then it means that the next release has not yet been split off from develop.

There will always be a branch called develop that is used to collect new features. The develop branch should provide a reasonably stable version that could be turned into a release relatively easily. Anything that is merged into develop represents something that will be included in the next release branch, so a decision to merge a feature into develop is a commitment to include it the next version of WeBWorK (or the "next next" one). This means that the feature is ready, or nearly ready, for production use. In development terms this means your feature has to be out of "alpha" and well into "beta". Most developers should base their working branches off of develop.

Occasionally there may be "feature" branches which contain very new code that has yet to be pulled into develop. This is only done for large features which might destabilize the develop branch and need to be worked on collaboratively before being merged into develop. You shouldn't base a working branch off of one of these feature branches unless you are writing code specifically for that feature.