changes:announcement-generate

Full name:

org.apache.maven.plugins:maven-changes-plugin:2.7.1:announcement-generate

Description:

Goal which generate the template for an announcement.

Attributes:

  • Requires a Maven project to be executed.
  • Requires dependency resolution of artifacts in scope: test.
  • The goal is thread-safe and supports parallel builds.
  • Since version: 2.0-beta-2.

Required Parameters

Name Type Since Description
basedir String 2.1 The current project base directory.
developmentTeam String 2.0-beta-2 Name of the team that develops the artifact. This parameter will be passed to the template.
Default value is: ${project.name} team.
finalName String 2.0-beta-2 The name of the artifact to be used in the announcement.
Default value is: ${project.build.finalName}.
generateJiraAnnouncement boolean 2.0-beta-2 Deprecated. Since version 2.4 this parameter has been deprecated. Please use the issueManagementSystems parameter instead.
Default value is: false.
maxEntries int 2.0-beta-2 The maximum number of issues to fetch from JIRA.

Note: In versions 2.0-beta-3 and earlier this parameter was called "nbEntries".


Default value is: 25.
outputDirectory File 2.0-beta-2 Directory where the template file will be generated.
template String 2.0-beta-2 The Velocity template used to format the announcement.
Default value is: announcement.vm.
templateDirectory String 2.0-beta-2 Directory that contains the template.

Note: This directory must be a subdirectory of /src/main/resources/ or current project base directory.


Default value is: org/apache/maven/plugin/announcement.
version String 2.0-beta-2 Version of the artifact.
Default value is: ${project.version}.
xmlPath File 2.0-beta-2 The path of the changes.xml file.

Optional Parameters

Name Type Since Description
announceParameters Map 2.1 Map of custom parameters for the announcement. This Map will be passed to the template.
announcementFile String 2.4 The name of the file which will contain the generated announcement. If no value is specified the plugin will use the name of the template.
filter String 2.4 Defines the filter parameters to restrict which issues are retrieved from JIRA. The filter parameter uses the same format of url parameters that is used in a JIRA search.
introduction String 2.0-beta-2 Short description or introduction of the released artifact. This parameter will be passed to the template.
Default value is: ${project.description}.
issueManagementSystems List 2.4 A list of issue management systems to fetch releases from. This parameter replaces the parameters generateJiraAnnouncement and jiraMerge.

Valid values are: changes.xml and JIRA.

Note: Only one issue management system that is configured in <project>/<issueManagement> can be used. This currently means that you can combine a changes.xml file with one other issue management system.
issueTypes Map 2.6 Maps issues types to action types for grouping issues in announcements. If issue types are not defined for a action type then the default issue type will be applied.

Valid action types: add, fix and update.
jiraMerge boolean 2.1 Deprecated. Since version 2.4 this parameter has been deprecated. Please use the issueManagementSystems parameter instead.
Default value is: false.
jiraPassword String 2.1 Defines the JIRA password for authentication into a private JIRA installation.
jiraUser String 2.1 Defines the JIRA username for authentication into a private JIRA installation.
resolutionIds String 2.0-beta-2 Include issues from JIRA with these resolution ids. Multiple resolution ids can be specified as a comma separated list of ids.

Note: In versions 2.0-beta-3 and earlier this parameter was called "resolutionId".


Default value is: Fixed.
runOnlyAtExecutionRoot boolean 2.3 This will cause the execution to be run only at the top of a given module tree. That is, run in the project contained in the same folder where the mvn execution was launched.
Default value is: false.
statusIds String 2.0-beta-2 Include issues from JIRA with these status ids. Multiple status ids can be specified as a comma separated list of ids.

Note: In versions 2.0-beta-3 and earlier this parameter was called "statusId".


Default value is: Closed.
templateEncoding String 2.1 The template encoding.
Default value is: ${project.build.sourceEncoding}.
tracPassword String 2.4 Defines the Trac password for authentication into a private Trac installation.
tracQuery String 2.4 Defines the Trac query for searching for tickets.
Default value is: order=id.
tracUser String 2.4 Defines the Trac username for authentication into a private Trac installation.
url String 2.0-beta-2 Distribution URL of the artifact. This parameter will be passed to the template.
urlDownload String 2.0-beta-2 URL where the artifact can be downloaded. If not specified, no URL is used. This parameter will be passed to the template.
versionPrefix String 2.5 The prefix used when naming versions in JIRA.

If you have a project in JIRA with several components that have different release cycles, it is an often used pattern to prefix the version with the name of the component, e.g. maven-filtering-1.0 etc. To fetch issues from JIRA for a release of the "maven-filtering" component you would need to set this parameter to "maven-filtering-".
webPassword String 2.4 Defines the http password for basic authentication into the JIRA webserver.
webUser String 2.4 Defines the http user for basic authentication into the JIRA webserver.

Parameter Details

announceParameters:

Map of custom parameters for the announcement. This Map will be passed to the template.
  • Type: java.util.Map
  • Since: 2.1
  • Required: No

announcementFile:

The name of the file which will contain the generated announcement. If no value is specified the plugin will use the name of the template.
  • Type: java.lang.String
  • Since: 2.4
  • Required: No
  • Expression: ${changes.announcementFile}

basedir:

The current project base directory.
  • Type: java.lang.String
  • Since: 2.1
  • Required: Yes
  • Expression: ${basedir}

developmentTeam:

Name of the team that develops the artifact. This parameter will be passed to the template.
  • Type: java.lang.String
  • Since: 2.0-beta-2
  • Required: Yes
  • Expression: ${changes.developmentTeam}
  • Default: ${project.name} team

filter:

Defines the filter parameters to restrict which issues are retrieved from JIRA. The filter parameter uses the same format of url parameters that is used in a JIRA search.
  • Type: java.lang.String
  • Since: 2.4
  • Required: No

finalName:

The name of the artifact to be used in the announcement.
  • Type: java.lang.String
  • Since: 2.0-beta-2
  • Required: Yes
  • Expression: ${changes.finalName}
  • Default: ${project.build.finalName}

generateJiraAnnouncement:

Deprecated. Since version 2.4 this parameter has been deprecated. Please use the issueManagementSystems parameter instead.
Flag to determine if the plugin will generate a JIRA announcement.
  • Type: boolean
  • Since: 2.0-beta-2
  • Required: Yes
  • Expression: ${generateJiraAnnouncement}
  • Default: false

introduction:

Short description or introduction of the released artifact. This parameter will be passed to the template.
  • Type: java.lang.String
  • Since: 2.0-beta-2
  • Required: No
  • Default: ${project.description}

issueManagementSystems:

A list of issue management systems to fetch releases from. This parameter replaces the parameters generateJiraAnnouncement and jiraMerge.

Valid values are: changes.xml and JIRA.

Note: Only one issue management system that is configured in <project>/<issueManagement> can be used. This currently means that you can combine a changes.xml file with one other issue management system.
  • Type: java.util.List
  • Since: 2.4
  • Required: No

issueTypes:

Maps issues types to action types for grouping issues in announcements. If issue types are not defined for a action type then the default issue type will be applied.

Valid action types: add, fix and update.

  • Type: java.util.Map
  • Since: 2.6
  • Required: No

jiraMerge:

Deprecated. Since version 2.4 this parameter has been deprecated. Please use the issueManagementSystems parameter instead.
If releases from JIRA should be merged with the releases from a changes.xml file.
  • Type: boolean
  • Since: 2.1
  • Required: No
  • Expression: ${changes.jiraMerge}
  • Default: false

jiraPassword:

Defines the JIRA password for authentication into a private JIRA installation.
  • Type: java.lang.String
  • Since: 2.1
  • Required: No
  • Expression: ${changes.jiraPassword}

jiraUser:

Defines the JIRA username for authentication into a private JIRA installation.
  • Type: java.lang.String
  • Since: 2.1
  • Required: No
  • Expression: ${changes.jiraUser}

maxEntries:

The maximum number of issues to fetch from JIRA.

Note: In versions 2.0-beta-3 and earlier this parameter was called "nbEntries".

  • Type: int
  • Since: 2.0-beta-2
  • Required: Yes
  • Expression: ${changes.maxEntries}
  • Default: 25

outputDirectory:

Directory where the template file will be generated.
  • Type: java.io.File
  • Since: 2.0-beta-2
  • Required: Yes
  • Expression: ${project.build.directory}/announcement

resolutionIds:

Include issues from JIRA with these resolution ids. Multiple resolution ids can be specified as a comma separated list of ids.

Note: In versions 2.0-beta-3 and earlier this parameter was called "resolutionId".

  • Type: java.lang.String
  • Since: 2.0-beta-2
  • Required: No
  • Expression: ${changes.resolutionIds}
  • Default: Fixed

runOnlyAtExecutionRoot:

This will cause the execution to be run only at the top of a given module tree. That is, run in the project contained in the same folder where the mvn execution was launched.
  • Type: boolean
  • Since: 2.3
  • Required: No
  • Expression: ${announcement.runOnlyAtExecutionRoot}
  • Default: false

statusIds:

Include issues from JIRA with these status ids. Multiple status ids can be specified as a comma separated list of ids.

Note: In versions 2.0-beta-3 and earlier this parameter was called "statusId".

  • Type: java.lang.String
  • Since: 2.0-beta-2
  • Required: No
  • Expression: ${changes.statusIds}
  • Default: Closed

template:

The Velocity template used to format the announcement.
  • Type: java.lang.String
  • Since: 2.0-beta-2
  • Required: Yes
  • Expression: ${changes.template}
  • Default: announcement.vm

templateDirectory:

Directory that contains the template.

Note: This directory must be a subdirectory of /src/main/resources/ or current project base directory.

  • Type: java.lang.String
  • Since: 2.0-beta-2
  • Required: Yes
  • Expression: ${changes.templateDirectory}
  • Default: org/apache/maven/plugin/announcement

templateEncoding:

The template encoding.
  • Type: java.lang.String
  • Since: 2.1
  • Required: No
  • Expression: ${changes.templateEncoding}
  • Default: ${project.build.sourceEncoding}

tracPassword:

Defines the Trac password for authentication into a private Trac installation.
  • Type: java.lang.String
  • Since: 2.4
  • Required: No
  • Expression: ${changes.tracPassword}

tracQuery:

Defines the Trac query for searching for tickets.
  • Type: java.lang.String
  • Since: 2.4
  • Required: No
  • Default: order=id

tracUser:

Defines the Trac username for authentication into a private Trac installation.
  • Type: java.lang.String
  • Since: 2.4
  • Required: No
  • Expression: ${changes.tracUser}

url:

Distribution URL of the artifact. This parameter will be passed to the template.
  • Type: java.lang.String
  • Since: 2.0-beta-2
  • Required: No
  • Expression: ${project.url}

urlDownload:

URL where the artifact can be downloaded. If not specified, no URL is used. This parameter will be passed to the template.
  • Type: java.lang.String
  • Since: 2.0-beta-2
  • Required: No

version:

Version of the artifact.
  • Type: java.lang.String
  • Since: 2.0-beta-2
  • Required: Yes
  • Expression: ${changes.version}
  • Default: ${project.version}

versionPrefix:

The prefix used when naming versions in JIRA.

If you have a project in JIRA with several components that have different release cycles, it is an often used pattern to prefix the version with the name of the component, e.g. maven-filtering-1.0 etc. To fetch issues from JIRA for a release of the "maven-filtering" component you would need to set this parameter to "maven-filtering-".

  • Type: java.lang.String
  • Since: 2.5
  • Required: No
  • Expression: ${changes.versionPrefix}

webPassword:

Defines the http password for basic authentication into the JIRA webserver.
  • Type: java.lang.String
  • Since: 2.4
  • Required: No
  • Expression: ${changes.webPassword}

webUser:

Defines the http user for basic authentication into the JIRA webserver.
  • Type: java.lang.String
  • Since: 2.4
  • Required: No
  • Expression: ${changes.webUser}

xmlPath:

The path of the changes.xml file.
  • Type: java.io.File
  • Since: 2.0-beta-2
  • Required: Yes
  • Expression: ${basedir}/src/changes/changes.xml