From GUS Wiki
Jump to: navigation, search

Proposal for managing GUS versions

The three main components of this proposal are

    • splitting the GUS Schema and the GUS Application Framework into separate projects
    • for both projects, using a standard three part version number
    • an approach for when we branch and how we maintain branched code

Splitting GUS in to Schema and Appl. Framework

The GUS project currently houses both the schema and the application framework, spread across a number of components. Instead, we would break the GUS-Schema and the GUS-AppFrmwk into two projects, with components beneath as required. The GUS-AppFrmwk project declares (in its build.xml file) a dependency on GUS-Schema

The primary benefit of this change is that we can give each project their own three part version number (more on that below). An additional benefit is that they can be released separately. It may turn out that the schema stays stable for a while, but the application framework is advancing rapidly. It will is a clean solution to let the application framework advance its releases while the schema stays on a stable release.

Three part version numbers

Both the schema and the application framework have their own independent three part version number. Their independence means that by scrutinizing the version numbers alone there is no way to know if a given version of one is compatible with a given version of the other. That compatibility information is made available on the GUS download site (in a clear fashion as yet to be determined).

In the case of the schema, the version number is of the form


The typical release advances the minor number (setting veryminor to 0). We use veryminor rather than bugfix because it is not typical for a schema to have a bug. But what is common is for it to undergo adjustments that are backwards compatible (eg, making a column allow nulls). We call those "very minor." Major versions are ones in which many tables change and/or many tables are added and/or deleted.

In the case of the application framework, the version is of the form


The meanings of these are familiar to all. A patch represents a set of one or more bug fixes.

Note: The author of the proposal did much work to try to provide a single version number that would encompass both the schema and the application framework and also distinguish between when one changed or the other. None, including cumbersome for number systems were workable.

Managing branches

Both the GUS-Schema and GUS-AppFrmwk projects are stored in a source code repository. As their development moves forward, they will both use a similar strategy for managing releases using branches in the repository.

Up until release 3.5 GUS has not had any systematic or rigorous approaches to releases. Instead, users of GUS acquired the development version of the system directly from the repository. This has the obvoius drawback that users have unstable software, and no two users are likely to have exactly the same software.

GUS will now adopt standard practice for releases. This explanation will use the GUS-Schema project as an example. Now that release 3.5 is complete, the trunk of the repository is presumed to hold development that is aiming towards release 3.6. When the feature set designated for 3.6 is complete, we create a branch in the repository tagged "3.6". The trunk is now available for 3.7 development. The 3.6 branch undergoes final testing and corrections. When that process is complete the branch is tagged with "3.6.0", and source is bundled for distribution and made available on the download site. Inevitably minor problems or "bugs" will be unearthed by the users. As these are corrected, the source is advanced through the 3.6.1, 3.6.2, etc. The branch is tagged each time and the source rebundled for distribution.

The great advantage of branches is that they can be developed independently from the trunk. The concomittant disadvantage is that there are multiple versions of the source, and many changes to one must be propogated to the other branches.

Using our example from above, as corrections are made in the 3.5 branch, the developer who makes them is obligated to propogate those changes to the trunk (if applicable). The reverse is also true. If a bug or correction is discovered in the trunk that applies to the branch, the developer must propagate. The obvious weakness in this system is that it is prone to human error. There are also options of mechanized merging available from the repository system, but those carry their own problems. So the proposed approach is to place the responsibility with the developers.

Because the typical rhythm of development is that there is a currently supported release on a branch, and the main development on the trunk, there is typically only two versions of the source.

Another reason to create a branch is to begin the development of a radical change to the source. For example, it might be that we begin development of the 4.0 version of the GUS schema, and that it is so different we expect there will be a few more releases of the 3.x series before we are ready to release 4.0. In this case, we create a branch for 4.0. This offers the same advantages and disadvantages of any branch: isolation but merging of changes required. This becomes particularly tricky as the 4.0 source diverges from the 3.x trunk.