Difference between revisions of "Library Component Versions"

Latest revision as of 22:33, 7 March 2010

Overview

In the ADF library versioning schema, sequence-based identifiers are used to convey the significance of changes between releases: changes are classified by significance level, and the decision of which sequence to change between releases is based on the significance of the changes from the previous release, whereby the first sequence is changed for the most significant changes, and changes to sequences after the first represent changes of decreasing significance.

The ADF library components follows this version schema:

major_minor_revisions

In this schema, the ADF uses a three-sequence identifier, the first sequence may be incremented only when the code is completely rewritten, while a change to the function or the documentation may only warrant a change to the thrid sequence.

The major number is increased when there are significant jumps in functionality, the minor number is incremented when only minor features or significant fixes have been added, and the revision number is incremented when minor bugs are fixed. A typical component might use the numbers 0.9 (for beta software), 0.9.1, 0.9.2, 0.9.3, 1.0, 1.0.1, 1.0.2, 1.1, 1.1.1, 2.0, 2.0.1, 2.0.2, 2.1, 2.1.1, 2.1.2, 2.2, etc. Developers have at times jumped (for example) from version 5.0 to 5.5 to indicate that significant features have been added, but not enough to warrant incrementing the major version number, though this is improper.

Example of a major revision

Here are a few examples of major revisions of ADF Library Components

Overhaul of internal methods

scripts_1_0.cfc is the ADF Library Component that is used to load external 3rd party JavaScript libraries (e.g. jQuery). It is coded to work with scriptService_1_0.cfc to manage which scripts are loaded into a page. scriptService_1_0.cfc uses a request scope variable "request.scriptsExecuted". If you were to make a modification to scripts_1_0.cfc to do internal script management (e.g. not to use scriptService_1_0) and modified each of the methods to use the new script management framework.

Culmination of many minor revisions

Eventually, when many minor revisions are made (e.g. scripts_1_22) it makes more sense to "reset" the component (e.g scripts_2_0).

Example of minor revision

Here are a few examples of minor revisions of ADF Library Components

Modified attributes

ceData_1_0.cfc has a method called getCEData() with the following attributes:

• customElementName
• customElementFieldName
• item
• queryType
• searchValues
• searchFields

If you were to add some new functionality to getCEData() so that it took an XML variable for the search criteria and subsequently removed queryType, searchValues and searchFields and ceData_1_0.cfc now had the following attributes:

• customElementName
• customElementFieldName
• item
• xmlQueryParams

You would want to give this cfc a new minor version (e.g. csData_1_1.cfc)

Change return type for a method

ceData_1_0.cfc contains a method called getAllCustomElements which currently returns a query object. If you were to modify this function to return a structure or an array of structures you would want to give ceData_1_0.cfc a new minor version (e.g. csData_1_2.cfc)

New method

If you were to add a new method to ceData_1_0.cfc (e.g. getCountForElementField) you would want to give ceData_1_0.cfc a new minor version (e.g. csData_1_3.cfc)

Delete method

The removal of any method (e.g. obsolete) would require a new minor version - (e.g. csData_1_4.cfc)

Example of Non major/minor revisions

Any revision to existing methods without modifying the attributes or the return variables would not require a major or minor revision. Essentially, a change of this kind would essentially be seen as a bug fix.

It is important however to update the "version" property tag in the component 
<cfproperty name="version" value="1_0_0">
Note: the name carries the major/minor (e.g. ceData_1_0) whereas the 
<cfproperty> tag carries the entire version