From EgeeWiki

This article deals with creating CVS tags and related etics configurations in a consistent manner across the whole LB suite.

Contents 1 Release Tags 2 Tagging Individual Modules 2.1 User Instructions 2.1.1 Command Line Options 2.1.2 Script Inetrnals 2.1.2.1 Preparation 2.1.2.2 Execution 2.2 Expected Results 3 Tagging Subsystems with Multiple Modules 3.1 User Instructions 3.1.1 Command Line Options 3.1.2 Script Inetrnals 3.1.2.1 Preparation 3.1.2.2 Execution 3.2 Expected Results 3.3 Testing 4 Checking Consistency 4.1 Usage 5 Generating Branch (AKA _dev) Configurations 5.1 Usage 5.1.1 Tagging Single Modules 5.1.1.1 Example 5.1.2 Tagging Subsystems 5.1.2.1 Example

Release Tags

Release tags in the L&B environment consist of the identification of the module, the _R_ literal, and version numbers separated by underscores. For example, the correct tag for module org.glite.lb.client version 4.0.0-2 is glite-lb-client_R_4_0_0_2 (note that the org. prefix has been dropped). That tag would be used for all the module's files stored in the CVS and also as the name of the corresponding etics configuration. When tagging the whole subsystem (e.g. org.glite.lb), the tag is used not only for the subsytem's base module (org.glite.lb) but for all related submodules as well (i.e. org.glite.lb.*);

Version numbers represent – in that order – the major version, the minor version, the revision, and the age of the product. As the product evolves, they are incremented to reflect the changes. When registering new tags, you need to decide which component of the version number to increment. As a rule of thumb, follow this:

• Age – Fixes and updates in the build process (including ETICS configurations), minor bug fixes
• Revision – Bux fixes
• Minor Version – New features
• Major Version – API/ABI changes

Tagging Individual Modules

The module tagging process is supported by the org.glite.lb/etics-tag.pl script. Make sure you have the TMPDIR environment variable set before you run it.

Note that he script itself does not modify anything. Instead, it produces an executive script you may double-check before running.

User Instructions

Before you begin, consider checking the source tree you have on your hands.

Then follow these steps for each module you want tagged:

1. Determine which section of the version designation (major version number, minor version number, revision, or age) do you want to increment, Usually, you will take a look at changes done since the last tag has been registered, and then decide.
2. Run the org.glite.lb/etics-tag.pl script. There is one mandatory argument – the name of the module (e.g. org.glite.lb.client). Other arguments are optional but it is recommended to specify the -i <version component> option.
   • Unless you specified the -i option, the script will display diff output comparing the last release-tagged version of the module to its current state, and then ask you to choose what to increment.
3. The script will invoke an editor and ask you to update the ChangeLog file. Give a brief description of changes.
4. Once finished, the script will print out the locations of files it has produced. There are three outputs:
   1. An executive script implementing the actual changes.
   2. A ChangeLog candidate.
   3. An etics configuration file (INI format accepted by the etics-configuration tool).
5. Check the output files and run the script.

Command Line Options

The org.glite.lb/etics-tag.pl script accepts the following options:

usage: org.glite.lb/etics-tag.pl [-i maj|min|rev|age|none|<sigle_word_age>] [-g] [-c <current configuration> ] module.name

	-i	What to increment ('maj'or version, 'min'or version, 'rev'ision, 'age')
		Should you fail to specify the -i option the script will open up a cvs diff
		output and ask you to specify what to increment interactively.
		'none' means no change -- this basically just generates a configuration.
	-g	Generate old configuration for comparison
	-c	Use this configuration (d+.d+.d+-S+) rather than parsing version.properties
	-m	Use this as a CVS commit message instead of the script's default.
	-h	Display this help

Script Inetrnals

Preparation

org.glite.lb/etics-tag.pl is a preparatory script and carries out the following actions (unless you modify its behavior by means of command line options):

1. Find out what is the current version of the given module by looking in <module name>/project/version.properties.
2. Display the difference between the module's current state and the last tagged state.
3. Ask the user to specify which component of the version number is to be incremented.
4. Prepare new version.properties
5. Ask the user to update the ChangeLog
6. Call configure --mode=etics to create a new configuration matching the new version

Besides these direct actions, the script also produces and execution script that carries out actual modifications as follows:

Execution

The execution script:

1. Copies and commits the new version of the ChangeLog
2. Generates and commits new version.properties.
3. Copies the most recent version of the configure script from org.glite.lb and commits it.
   • The configure script can be used to build each of the modules separately, without the need to have org.glite.lb as a dependency.
4. Calls cvs tag' to tag the module.
5. Calls etics-configuration add to create the new configuration.

Expected Results

This process creates a unique release tag for the given module, uses it to tag all files stored in the CVS, and creates an etics configuration matching the name of the tag.

Tagging Subsystems with Multiple Modules

This needs to be carried out once you have tagged all modules that have changed. Currently, the process supports the following subsystems:

• org.glite.lb
• org.glite.lpjp-common
• org.glite.jobid

The subsystem tagging process is supported by the org.glite.lb/etics-tag-with-subsystems.pl script. Make sure you have the TMPDIR environment variable set before you run it.

Note that he script itself does not modify anything. Instead, it produces an executive script you may double-check before running.

User Instructions

Follow these steps for the subsystem you want tagged:

1. Run the org.glite.lb/etics-tag-with-subsystems.pl script. There is one mandatory argument – the name of the module (e.g. org.glite.lb). The script will iterate through all the subsystem's modules and check for version changes.
2. Once finished, the script will print out the locations of files it has produced. There are three outputs:
   1. An executive script implementing the actual changes.
   2. An etics configuration file (INI format accepted by the etics-configuration tool).
3. Check the output files and run the script.

Command Line Options

The org.glite.lb/etics-tag-with-subsystems.pl script accepts the following options:

usage: org.glite.lb/etics-tag-with-subsystems.pl [-c <current configuration>] module.name

        -c      Use this configuration (d+.d+.d+-S+) rather than parsing version.properties
        -h      Display this help

Script Inetrnals

Preparation

org.glite.lb/etics-tag-with-subsystems.pl is a preparatory script and carries out the following actions (unless you modify its behavior by means of command line options):

1. Find out what is the current version of the given module by looking in <module name>/project/version.properties.
2. Iterate through submodules, compare their current version.properties files to their previous versions tagged with the tag identified in step 1 and decide, which components of their respective version numbers have changed.
3. Prepare new version.properties
4. Call configure to create a new configuration matching the new version

Besides these direct actions, the script also produces and execution script that carries out actual modifications as follows:

Execution

The execution script:

1. Generates and commits new version.properties.
2. Calls cvs tag' to tag the module as well as all related subsystem modules.
3. Calls etics-configuration add to create the new configuration.

Expected Results

This process creates a unique release tag for the given module, uses it to tag all files stored in the CVS for that module and all related subsystem modules (for example, when tagging the org.glite.lb module, it also tags all the other org.glite.lb.* modules) and creates an etics configuration matching the name of the tag.

Testing

Once tagged, it should be possible to build the subsystem using etics. For example, to build the org.glite.jobid subsystem tagged with the glite-jobid_R_1_0_0_4 tag, do the following:

etics-workspace-setup
etics-get-project org.glite
etics-checkout --noask --project-config glite_branch_3_2_0_dev --config glite-jobid_R_1_0_0_4 org.glite.jobid
etics-build org.glite.jobid

Note that to build certain subsystems (such as org.glite.lb), you may need to specify the etics.properties file. See Building LB and JP with ETICS for more information on building org.glite.lb with etics.

Checking Consistency

The consistency checking script – org.glite.lb/etics-tag-consistency.pl – is used to check that no tags or configurations are missing from the current tree, and that they match each other. It accepts subsystem names as command line arguments and does the following for every module related to any of those:

• Check if project/version.properties file exists and parse it to find out what tag to expect.
• Check if the project/version.properties file is tagged with the expected tag.
• Check if the project/version.properties file is tagged with the subsystem's tag (found in the appropriate subsystem's version.properties).
• Check if the related etics configuration exists. (Note that this is not done by default. You need to specify the -c option to activate etics checking).
• Check if project/ChangeLog file exists.
• Check if the configure script exists.

The script may be run at any time and should always succeed (i.e. failure always indicates there is something wrong) but the two intended uses are these:

• Check the status of the source tree before you start tagging.
• Check the status of the source tree once you have finished tagging.

Usage

Use the following syntax to run the script:

usage: org.glite.lb/etics-tag-consistency.pl [-h] subsystem.name [subsystem.name] [...]

	This script checks the consistency of tags in CVS and version.properties

	-c	also verify etics configurations
	-h	Display this help

To run the full check for the whole LB suite, do the following:

org.glite.lb/etics-tag-consistency.pl -c org.glite.lb org.glite.jobid org.glite.lbjp-common

Should you wish to see the errors only, redirect the standard output:

org.glite.lb/etics-tag-consistency.pl -c org.glite.lb org.glite.jobid org.glite.lbjp-common > /dev/null

Note: To check etics configurations, you will need the script to contact the etics server using your identity. If you have not given etics the passphrase to your certificate key recently, it will prompt you for it once you run the script but – with command output redirected and filtered – you won't be able to see the password prompt. As a rule of thumb, should the script "freeze" for more that just a few seconds (with the -c option active), it is probably waiting for your password. You may enter it safely or terminate the script, run any other etics command requiring authentication (e.g. etics-list-configuration), and re-run the checking script.

Generating Branch (AKA _dev) Configurations

A pair of tools similar to etics-tag.pl and etics-tag-with-subsystems.pl may be used to generate etics configurations referring to existing CVS branches rather than newly created tags. These are named etics-tag-branch.pl and etics-tag-with-subsystems-branch.pl.

Note: These tools do not modify the CVS in any way. The branch must already be there.

Usage

In general, the usage is similar to the tagging scripts discussed above. The -b argument has been added, allowing users to specify the name of the branch.

Tagging Single Modules

$ org.glite.lb/etics-tag-branch.pl -h

usage: org.glite.lb/etics-tag-branch.pl -b <branch> [-c configuration] module.name

	-b	Name of the 'b'ranch to base the configuration on.
		The branch must already exist in CVS!

	-c      Use this configuration (d+.d+.d+-S+) rather than parsing 
		version.properties.  Bear in mind that  this will only be used
		to set up the version and age in your configuration. 
		Also, the existence of the branch will not be tested. with the
		-c option.

	-h	Display this help

Typically, the script will be called with the -b option and the name of the module. It generates a script and a configuration, and prints out their locations. Once checked, run the script and the configurations will be uploaded to etics.

Example

Creating a branch tag for module org.glite.lb.client, branch branch_2_0:

$ org.glite.lb/etics-tag-branch.pl -b branch_2_0 org.glite.lb.client

This creates the configuration, reading the version and age of the module from its etics.properties file. Version and age values are only entered in the version' and age fields of the configurations. They are not used anywhere else.

Tagging Subsystems

$ org.glite.lb/etics-tag-with-subsystems-branch.pl -h

usage: org.glite.lb/etics-tag-with-subsystems-branch.pl -b <branch> [-c configuration] subsystem.name

	-b	Name of the 'b'ranch to base the configuration on.
		The branch must already exist in CVS!

	-c      Use this configuration (d+.d+.d+-S+) rather than parsing 
		version.properties.  Bear in mind that  this will only be used
		to set up the version and age in your configuration. 
		Also, the existence of the branch will not be tested. with the
		-c option.

	-h	Display this help

Typically, the script will be called with the -b option and the name of the module. It generates a script and a configuration, and prints out their locations. Once checked, run the script and the configurations will be uploaded to etics.

Example

Creating a branch tag for subsystem org.glite.lb, branch branch_2_0:

$ org.glite.lb/etics-tag-with-subsystems-branch.pl -b branch_2_0 org.glite.lb

This creates the configuration, reading the version and age of the subsystem from its etics.properties file. Version and age values are only entered in the version and age fields of the configurations. They are not used to specify dependencies. The branch configuration of a subsystem always depends on relevant branch configurations of individual modules. For example, subsystem configuration glite-lb_branch_2_0 will depend on module configurations glite-lb-client_branch_2_0, glite-lb-common_branch_2_0, etc.