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