Overview
Commit message transformers can be used to alter how SCM commit messages appear when displayed in the pulse™ web interface. Commit messages are shown in various parts of the interface, where source code changes between builds are shown. The most common use for a commit message transformer is to create links out of certain key phrases. For example, the key phrase "bug 123" could be transformed into a link to a web-based bug tracker. Commit message transformers can more generally be used to make arbitrary changes to messages, such as stripping unwanted details and/or highlighting important information.
Adding Transformers
Transformers may be added via either the server settings page in the "administration" section, or via the "configuration" tab for a specific project. This reflects the fact that the same transformer may be applied to multiple projects. When configuring transformers in the administration section, you can select to which projects the transformer should be applied. When adding a new transformer via the configuration for a project, you have the option of creating a new transformer or selecting an existing one to apply to the project.
To create a new transformer, use the "add commit message transformer" link to enter the Add Commit Message Transformer Wizard. This first step of the wizard prompts you to select the type of transformer to create. The available types are described in the sections below. For all types you will be prompted to specify a name for the transformer: this should be a descriptive name as it is used to identify the transformer.
Custom Transformers
A custom transformer can be used to apply an arbitrary transformation to commit messages. To configure a custom transformer, you specify a regular expression to match the key phrase of interest, and a replacement to substitute for the key phrase. The regular expression is in Java format (similar to Perl format). The replacement may make use of group references to include parts or all of the matched key phrase, for example $0 can be used to refer to the entire matched phrase.
Note that the replacement will be displayed literally in the pulse™ web interface. This allows you to use HTML tags in the replacement. It also means that you must take care to escape HTML special characters in the replacement if you want them to appear literally. For example, you should use < and > for < and > respectively.
Examples
Remove all text up to the first colon
Use the regular expression:
and an empty replacement string.
Turn all occurences of the word "error" red
Use the expression:
and the replacement:
Jira Transformers
A Jira transformer is used to integrate with Atlassian Jira
. It will link from Jira keys (e.g. FOO-123) to the corresponding issue page in a Jira instance. To configure a Jira transformer, just provide the URL to your Jira instance.
Example
Link Transformers
A link transformer is a convenient way to add a transformer that turns an arbitrary key phrase into a link. A common use for such a transformer would be to link references to bugs to the bug tracker interface, for bug trackers that are not directly supported. To configure a link transformer, you must provide a regular expression to match the key phrase of interest, and a URL to link the key phrase to. As with custom transformers, the regular expression is in Java format. The URL to link to may also include group references (e.g. $1) for groups captured within the regular expression.
Example
Link to Bugzilla bugs
Use the regular expression:
and the URL:
Managing Transforners
Project Configuration
You can edit the configuration for an existing transformer by clicking the "edit" link in the corresponsing row of the "commit message transformers" table. To stop applying a transformer to the project, use the corresponding "delete" link. Note that this will not remove the transformer from pulse™ as it may still be in use by other projects.
Server Settings
You can edit the configuration for an existing transformer by clicking the "edit" link in the corresponsing row of the "commit message transformers" table. To change the projects that the transformer is applied to, click the link in the "projects" column. To delete a transformer, use the corresponding "delete" link.
