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, a single stable branch and a single development branch. Previous versions are indicated by a tag.

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

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

In general there will be no back-porting of features to legacy versions. Due to resource limitations bug fixes and security patches may not be back-ported to previous 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 permanent branches, main and devel. The main 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. Note that when a new version of the software is merged into the main branch, it may require changes to the configuration files and database.

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 main so that master always represents the current release.

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. Although the level branch is intended to be stable, there is no guarantee that it is suitable for use in production environments at any point in time.

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 major features are added to the branch, and the devel branch is now considered to be working toward the next release (e.g., 3.1). 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 main. At this point, the version tag (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 main (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 main will not reintroduce it).

The main repository will contain only the main, 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 Schedule

Currently the development team strives to release a new version once per year. The proposed schedule is to publish a release candidate in the Spring. After feedback has been obtained the official release is intended to happen in the Summer.