LEA Program and Parameter Version Numbers

Back to:

Introduction

Every Lynx program has a version number, which appears whenever the program is executed.

Programs require version numbers in order to track updates, modifications, improvements and bug fixes and to keep documentation, parameter definitions and parameter files synchronised as the program evolves.

Program Version Numbers

Whenever the source code of a program is updated, a new version number, date, programmer initials and details of modifications must be entered in the comments header section at the top of the program. The standard format should be strictly adhered to, see below:

V1.00 01/08/95 XX Origin Date 
........... 
V1.29 10/09/96 YY Added some other modifications...

The first V character should be separated from the comment symbol at the beginning of the line by one whitespace character. XX and YY represent the programmer's initials.

In the case of C programs, the V will be the fourth character on the line, eg

/* V1.00 .

In the case of Pascal or Fortran programs the V will be the third character, eg

{ V1.01

C V1.02

For BASIC programs it will be the fifth character, and so on, eg

REM V1.03

The date should be separated from the version number by one whitespace character and be in the form DD/MM/YY. The years 2000, 2001 etc. will be represented by 00, 01 etc.

The description of the modifications made should be separated from the data by at least one whitespace character. If the description extends over more than one line, the second and subsequent lines should be left justified to the align with the first line.

Updating Program Version Numbers

Each digit in the program version numbers has a specific function :

V 1.2 3

The first (one or more digits) before the decimal point should only be increased if there is major restructuring involved which will mean many changes both in the source code and in the documentation. Also increase this digit if the display will be significantly changed or if a new compiler is used.
The second digit should be increased whenever modifications occur which require changes in the documentation or the definition of the program's setup or parameters. In the case of a subroutine or procedure library or unit, any change in the argument list of any existing subroutine will result in this number being changed. Adding a new subroutine will not necessarily require this digit to be changed, because, presumably, existing programs could not already be using it and providing that existing subroutine argument lists remain the same, there should not be a problem.
The third digit will probably be changed the most often. Any bug fixes or minor modifications which do not need changes to the documentation should cause this digit to increase.

In this context, "digits" can be either alpha characters (A to F) or numeric characters. Within the program source itself, the version number should be coded as a manifest string literal constant, eg in Pascal:

ProgVersion = 'V4.12';

Procedure and Function Libraries

Procedure and function libraries, although not executable, should follow the same general documentation rules as for program source code and should have a source code version number. Changes (bug fixes) to any code in the library require the third digit to be updated. Changes in the specifications of argument lists, or to the results of any procedure or function require the second digit to be incremented. Major restructuring requires the first digit to be changed.

INI file Version checking

INI files have a version=version range string in the [lynx] section of the file. The version string contains a version number or range of version numbers for the corresponding program or library module which uses the INI file.

The version range string is in the form of a comma delimited list, in which the individual list items can be either single version numbers, eg V4.56, or version number ranges, eg V1.00-V2.05. For example the string

version=V1.05,V2.00-V2.30,V3.0

Means "V1.05 or V3.0 or any version number in the range V2.00 to V2.30".

Parameter file versions

Where Lynx Exploration Archivist programs have parameters, these will be defined in the program's INI file. The [lynx] section of the INI file contains a version key which defines the range of program version numbers for which the INI file is valid.

Parameter files are matched with the corresponding INI file, by comparing their version number against the version range in the INI file. If the program's parameter definition is changed in some way (so that the internal variables are no longer compatible with the INI file), and the INI file's version range is correctly specified, then old parameter files will not match.

Parameter files can be read and written by the parameter editor, without any knowledge of a corresponding program version number - the version written into the parameter file will then be the highest version number in the range in the INI version string.

Help documentation

Help documentation for individual programs will normally be named with the program executable file name plus the appropriate extension. Versions of 3S/LEA later than 3S20 should use HTML as the preferred format for manuals, although the format used is selectable at run time on an individual program basis.

Program help documentation version numbers should only show the first two digits of the program version number (e.g. V1.2), because minor modifications to programs requiring the third digit to change do not entail changes to the manual