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.9</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.
VariableTypeSinceDescription
releases*List2.0All the releases from either the changes.xml file or from JIRA.
groupId*String2.0The groupId from your project's pom.
artifactId*String2.0The artifactId from your project's pom.
version*String2.0The version from your project's pom.
packaging*String2.0The packaging from your project's pom.
release*Release2.0The release that you are announcing.
project*MavenProject2.1The Maven Project being released.
urlString2.0Distribution url of the artifact. Default value is: ${project.url}.
introductionString2.0A short description or introduction of the released artifact. Default value is: ${project.description}.
developmentTeamString2.0Name of the team that develops the artifact. Default value is: ${project.name} team.
finalNameString2.0The name of the artifact to be used in the announcement. Default value is: ${project.build.finalName}.
urlDownloadString2.0URL where the artifact can be downloaded. Default value is: ${project.url}.
announceParametersMap2.1A 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.
VariableTypeSinceDescription
actions*List2.0All actions that were completed in this release.
dateRelease*String2.0The date when this release is made.
description*String2.0A description of the release.
version*String2.0The version of this release.

Finally each Action has the following variables:

Variables marked with * are read-only.
VariableTypeSinceDescription
action*String2.0What was done.
dev*String2.0The developer who made the change.
dueTo*String2.0If this was a contribution from a non-developer, the name of that person.
dueToEmail*String2.0If this was a contribution from a non-developer, the e-mail address of that person.
issue*String2.0The key of the issue in your issue tracking system.
type*String2.0What 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.