 ------
 Using a Custom Announcement Template
 ------
 Dennis Lundberg
 ------
 2011-03-30
 ------

 ~~ Licensed to the Apache Software Foundation (ASF) under one
 ~~ or more contributor license agreements.  See the NOTICE file
 ~~ distributed with this work for additional information
 ~~ regarding copyright ownership.  The ASF licenses this file
 ~~ to you under the Apache License, Version 2.0 (the
 ~~ "License"); you may not use this file except in compliance
 ~~ with the License.  You may obtain a copy of the License at
 ~~
 ~~   http://www.apache.org/licenses/LICENSE-2.0
 ~~
 ~~ Unless required by applicable law or agreed to in writing,
 ~~ software distributed under the License is distributed on an
 ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 ~~ KIND, either express or implied.  See the License for the
 ~~ specific language governing permissions and limitations
 ~~ under the License.

 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/doxia/references/apt-format.html


Using a Custom Announcement Template

 The <<<announcement-generate>>> goal uses a {{{http://velocity.apache.org/}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>${project.version}</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
 {{{http://svn.apache.org/repos/asf/maven/plugins/trunk/maven-changes-plugin/src/main/resources/org/apache/maven/plugins/announcement/announcement.vm}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:

*-----------------+----------+-----------+-----------------+
| <<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.
*-----------------+----------+-----------+-----------------+
<Variables marked with * are read-only.>

 Each <<<Release>>> also has a set of variables:

*-----------------+----------+-----------+-----------------+
| <<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.
*-----------------+----------+-----------+-----------------+
<Variables marked with * are read-only.>

 Finally each <<<Action>>> has the following variables:

*-----------------+----------+-----------+-----------------+
| <<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.
*-----------------+----------+-----------+-----------------+
<Variables marked with * are read-only.>

 Since 2.8 the Velocity Context contains all default tools as provided by the {{{http://velocity.apache.org/tools/devel/standalone.html}ToolManager}}.
 See the {{{http://velocity.apache.org/tools/devel/summary.html}Tools Usage Summary}} for further details. 

 For information on how to access variables in your template and more,
 please see the
 {{{http://velocity.apache.org/engine/releases/velocity-1.4/user-guide.html}Velocity user guide}}.