DevelopmentProcess

WeBWorK Development Process

The WeBWorK development community uses http://github.com to manage distributed development.

Development of WeBWorK follows a model which enables support of legacy versions, maintenance of a stable version, and an active development of new features for which will eventually become the new stable version.

At a moment in time, the github repository will have multiple legacy branches, a single stable branch, and a single development branch.

Legacy branches will receive security fixes only.

Development of the stable version will be restricted to bug fixes and minor features.

Development of major features will be carried out on the development branch.

In general be no backporting of features to legacy versions.

Work done on the development branch may break compatibility with previous versions of APIs, database schemas, etc; upgrading from a stable to a new version will generally require migration of existing configurations and data.

---

Overview

An important goal of the WeBWorK branching model is to make it clear which branches are stable releases, which are testing branches, and which are development branches. It should be easy for installers to obtain and maintain the version that they are interested in, and it should be easy for developers to know where to start their development efforts, and where to request their results be included. The version numbering scheme should make it clear which releases involve changes that might break existing practices, and which are simply bug fix or new feature releases.

The Branches

There are two main permanent branches, master and devel. The master branch should always represent the current stable release. Since this is the easiest branch to check out, this is the branch that installers are most likely to use, and since it is always the current release, those system administrators can remain current simply by updating their installation using that branch.

The releases will be tags on the master branch, so installers can check out a specific version number by these tags. When a new primary version (e.g., 3.0) is released, a branch is created for that version and its sub-releases. For version 3.0, this branch is named 3.x; sub-versions like 3.1 and 3.2 will be tags along this branch, and will be merged back into master so that master always represents the current release.

An installer who wants to remain within a particular primary version should check out one of the version branches (e.g., 3.x). He or she can update within that branch without much fear that things will break, and can control when to upgrade to a later version. To obtain another version, the installer simply checks out the branch for the next version (e.g., 4.x) to get the most current release of version 4.

The devel branch represents the most stable development version, and is the version that those interested in the latest new features and bug fixes should run. Features are included into this branch only if they are destined for the next release and are ready for field testing.

Feature development normally is done in feature branches housed in the developer's fork of the repository. These branches are not pushed directly to the main repository, but when a feature is ready for including in devel, the developer merges devel into their feature branch and then makes a pull request to include the branch into the devel branch of the main repository.

When the devel branch is nearly ready to be used as a release, a release branch is created for final testing of the release. E.g., release-3.0 would be such a branch in preparation for the 3.0 official release. From this point on, no new features are added to the branch, and the devel branch is now considered to be working toward the next release (e.g., 4.0). A pull request is made to include this in the master branch, which provides a place for public comments, error reports, and so forth. Fixes can be applied to this branch (these can be merged back to develop, but develop should not be merged to the release branch). When the release is deemed ready, the requested pull is performed, and the release is tagged on master. At this point, the version branch (3.x) is created.

Once a release is made, since it is intended as a stable release, it should not change. Should a critical bug be found that requires correction immediately, a hotfix branch can be created to make a correction. This will be merged into the version branch (making a new sub-version), and that is merged into master (if this is the highest version number). The hotfix is also merged into develop so that the fix is not lost in the next release. (If the bug is already fixed in the devel branch in another way, it should still be merged to develop and then edited out, so that a later merge to master will not reintroduce it).

The main repository will contain only the master, devel, version branches, and (when a release is being tested), the release candidate branch. The feature branches, hotfix branches, and any other testing branches appear only in developer forks of the repository.

Version Numbering

Version of WeBWorK and PG historically have had two, three, or even four version numbers. This branching model uses only primary and sub version numbers. Version 3.0 represents a major update that includes features that change past practices (e.g., new database structures, major UI changes, etc.), while version 3.1 represents a minor update that contains only bug fixes and new features that do not break older practices.

(release timing?)