Using a Custom Announcement Template

The announcement-generate goal uses a Velocity template to create an announcement. If you want to, you can create your own custom template.

Configuring the Plugin

First you must configure the plugin and tell it where your template is. In this example we want to use the template ${basedir}/src/main/resources/our-announcements/my-announcement.vm.

Note: The <templateDirectory> must be a subdirectory of ${basedir}/src/main/resources/.

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-changes-plugin</artifactId>
        <version>2.11</version>
        <configuration>
          <template>my-announcement.vm</template>
          <templateDirectory>our-announcements</templateDirectory>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>

Creating Your Template

Next you want to create your own template. A wise thing is to start with the default one that is included in the plugin. You can download it from Subversion here. It will provide you with examples on how to iterate over the actions of a release among other things.

Available Variables

Here's a list of the variables that you have at your disposal, when creating your own template:

Variables marked with * are read-only.
Variable Type Since Description
releases* List 2.0 All the releases from either the changes.xml file or from JIRA.
groupId* String 2.0 The groupId from your project's pom.
artifactId* String 2.0 The artifactId from your project's pom.
version* String 2.0 The version from your project's pom.
packaging* String 2.0 The packaging from your project's pom.
release* Release 2.0 The release that you are announcing.
project* MavenProject 2.1 The Maven Project being released.
url String 2.0 Distribution url of the artifact. Default value is: ${project.url}.
introduction String 2.0 A short description or introduction of the released artifact. Default value is: ${project.description}.
developmentTeam String 2.0 Name of the team that develops the artifact. Default value is: ${project.name} team.
finalName String 2.0 The name of the artifact to be used in the announcement. Default value is: ${project.build.finalName}.
urlDownload String 2.0 URL where the artifact can be downloaded. Default value is: ${project.url}.
announceParameters Map 2.1 A Map of custom parameters that can be specified in the plugin's configuration.

Each Release also has a set of variables:

Variables marked with * are read-only.
Variable Type Since Description
actions* List 2.0 All actions that were completed in this release.
dateRelease* String 2.0 The date when this release is made.
description* String 2.0 A description of the release.
version* String 2.0 The version of this release.

Finally each Action has the following variables:

Variables marked with * are read-only.
Variable Type Since Description
action* String 2.0 What was done.
dev* String 2.0 The developer who made the change.
dueTo* String 2.0 If this was a contribution from a non-developer, the name of that person.
dueToEmail* String 2.0 If this was a contribution from a non-developer, the e-mail address of that person.
issue* String 2.0 The key of the issue in your issue tracking system.
type* String 2.0 What kind of change was this.

Since 2.8 the Velocity Context contains all default tools as provided by the ToolManager. See the Tools Usage Summary for further details.

For information on how to access variables in your template and more, please see the Velocity user guide.