Overview
Some minor incompatibilities have been introduced between the 2.0 series and the 2.1 series. These are detailed below.
Pulse File Changes
The most significant change (compatibility wise) in pulse™ 2.1 is the unification of the configuration system and pulse files. All of the flexibility available in pulse files is now also available via the normal configuration system exposed in the web interface. This change required a rewrite of the pulse file parsing and underlying data structures to make use of the templated configuration system. Although in most cases compatibility is preserved, some details may differ. The most important differences are:
- The <command> element is now deprecated. Although still supported internally, it is now redundant and is no longer documented. In pulse™ 2.1 <artifact> and <dir-artifact> elements may be nested directly under any command (e.g. <make>), so a wrapping <command> is not necessary.
- The <resource> element is no longer supported. Instead, resource requirements should be expressed as part of the project or stage configuration outside of the Pulse file.
- The <version> element is no longer supported. With the addition of project dependencies, versions now have a more important and specific meaning in Pulse. We encourage you to use the dependencies version (under the "project dependencies" section of a project's configuration) where possible. Alternatively, a custom field can be used to specify your own type of version.
On upgrade, pulse™ will automatically convert the pulse files for custom projects. If you use versioned projects, however, manual intervention is required. To simplify the process pulse™ 2.1 includes a convertTo21 command.
convertTo21
A tool to convert pulse files from 2.0 to 2.1 is built into all pulse™ packages (developer tools, agents and master). To run the tool, invoke it via the pulse command, passing the input file then the output file as arguments. For example:
$ $PULSE_HOME/bin/pulse convertTo21 pulse-2.0.xml pulse-2.1.xml
If <resource> tags need to be removed from the file warnings will be issued.
The conversion tool may be applied to incomplete pulse files (i.e. those normally imported into another file). Note that in the case of imports and/or macros that the conversion may not always be complete. In that case you may need to edit the files by hand.
Directory Name Encoding
Where configurable names (e.g. project names) are used as directory names, encoding is used to ensure compatibility across different file systems. In Pulse 2.0, the www-form-url-encoding was used, which involves converting special characters to percent-encoded form (e.g. %2f). The exception to this was the space character, which is encoded as a plus (+). In Pulse 2.1, this exception has been removed: all special characters are percent encoded, so spaces are now encoded as %20. Thus, if you use spaces in your agent/project/stage names, you may see Pulse using new directory names for persistent working areas.
Unfortunately, the % character itself can cause issues in some environments (particularly on Windows). For this reason, it may be necessary to avoid encoding altogether by either:
- Renaming agents/projects/stages as necessary to avoid special characters in their names (e.g. by using underscores in place of spaces).
- Configuring Pulse to use handles (unique integer ids) in directory names instead. This can be done for the agent data directory pattern (root of your agent configuration) and project persistent work patterns (in the build options for the project).
Note that new Pulse installations use handles in directory names to avoid such encoding issues.
Validation
With the unification of pulse files and the configuration system there have also been some minor changes to validation rules. In most cases these will not affect your configuration. However, if you use special characters such as slashes in the names of some of your 2.0 configuration (perhaps in a pulse file), you may find the names no longer validate in pulse™ 2.1. In most cases this should be fixable by tweaking the name.
