------
 Using a Custom Announcement Template
 ------
 Dennis Lundberg
 ------
 7 July 2007
 ------

 ~~ 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 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>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-changes-plugin</artifactId>
        <configuration>
          <template>my-announcement.vm</template>
          <templateDirectory>our-announcements</templateDirectory>
        </configuration>
      </plugin>
    </plugins>
  </reporting>
  ...
</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/plugin/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>> | <<Contents>>
*-----------------+----------+-------------+
| releases*       | List     | All the releases from either the changes.xml file or from JIRA.
*-----------------+----------+-------------+
| groupId*        | String   | The groupId from your project's pom.
*-----------------+----------+-------------+
| artifactId*     | String   | The artifactId from your project's pom.
*-----------------+----------+-------------+
| version*        | String   | The version from your project's pom.
*-----------------+----------+-------------+
| packaging*      | String   | The packaging from your project's pom.
*-----------------+----------+-------------+
| url             | String   | Distribution url of the artifact. Default-value: <<<$\{project.url\}>>>.
*-----------------+----------+-------------+
| introduction    | String   | A short description or introduction of the released artifact. Default-value: <<<$\{project.description\}>>>.
*-----------------+----------+-------------+
| developmentTeam | String   | Name of the team that develops the artifact. Default-value: <<<$\{project.artifactId\}-team>>>.
*-----------------+----------+-------------+
| finalName       | String   | The name of the artifact to be used in the announcement. Default-value: <<<$\{project.build.finalName\}.$\{project.packaging\}>>>.
*-----------------+----------+-------------+
| urlDownload     | String   | URL where the artifact can be downloaded. Default-value: <<<$\{project.url\}>>>.
*-----------------+----------+-------------+
| release*        | Release  | The release that you are announcing.
*-----------------+----------+-------------+
<Variables marked with * are read-only.>

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

*-----------------+----------+-------------+
| <<Variable>>    | <<Type>> | <<Contents>>
*-----------------+----------+-------------+
| action*         | List     | All actions that were completed in this release.
*-----------------+----------+-------------+
| dateRelease*    | String   | The date when this release is made.
*-----------------+----------+-------------+
| description*    | String   | A description of the release.
*-----------------+----------+-------------+
| version*        | String   | The version of this release.
*-----------------+----------+-------------+
<Variables marked with * are read-only.>

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

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

 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}}.