changes:announcement-generate

Full name:

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

Description:

Goal which generate an announcement from the announcement template.

Attributes:

  • Requires a Maven project to be executed.
  • The goal is thread-safe and supports parallel builds.
  • Since version: 2.0-beta-2.

Required Parameters

Name Type Since Description
announcementDirectory File 2.10 Directory where the announcement file will be generated.
Default value is: ${project.build.directory}/announcement.
basedir String 2.1 The current project base directory.
User property is: basedir.
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.
User property is: changes.developmentTeam.
finalName String 2.0-beta-2 The name of the artifact to be used in the announcement.
Default value is: ${project.build.finalName}.
User property is: changes.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.
User property is: generateJiraAnnouncement.
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.
User property is: changes.maxEntries.
template String 2.0-beta-2 The Velocity template used to format the announcement.
Default value is: announcement.vm.
User property is: changes.template.
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.
User property is: changes.templateDirectory.
version String 2.0-beta-2 Version of the artifact.
Default value is: ${project.version}.
User property is: changes.version.

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.
User property is: changes.announcementFile.
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.
githubAPIPort int 2.9 The port of your github api domain. Only use if using github enterprise.
Default value is: 80.
User property is: changes.githubAPIPort.
githubAPIScheme String 2.9 The scheme of your github api domain. Only use if using github enterprise.
Default value is: http.
User property is: changes.githubAPIScheme.
githubAPIServerId String 2.12 The settings.xml server id to be used to authenticate into github api domain. Only use if using github enterprise.
Default value is: github.
includeOpenIssues boolean 2.0-beta-2 Boolean which says if we should include open github issues in the announcement.
Default value is: false.
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.


jiraConnectionTimeout int 2.11 Defines the connection timeout in milliseconds when accessing JIRA's REST-API.

Might help when you have a lot of different resolutions in your JIRA instance.


Default value is: 36000.
User property is: changes.jiraConnectionTimeout.
jiraMerge boolean 2.1 Deprecated. Since version 2.4 this parameter has been deprecated. Please use the issueManagementSystems parameter instead.
Default value is: false.
User property is: changes.jiraMerge.
jiraPassword String 2.1 Defines the JIRA password for authentication into a private JIRA installation.
User property is: changes.jiraPassword.
jiraReceiveTimout int 2.11 Defines the receive timeout in milliseconds when accessing JIRA's REST-API.

Might help when you have a lot of different resolutions in your JIRA instance.


Default value is: 32000.
User property is: changes.jiraReceiveTimout.
jiraUser String 2.1 Defines the JIRA username for authentication into a private JIRA installation.
User property is: changes.jiraUser.
outputDirectory File 2.0-beta-2 Deprecated. Starting with version 2.10 this parameter is no longer used. You must use announcementDirectory instead.
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.
User property is: changes.resolutionIds.
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.
User property is: announcement.runOnlyAtExecutionRoot.
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.
User property is: changes.statusIds.
templateEncoding String 2.1 The template encoding.
Default value is: ${project.build.sourceEncoding}.
User property is: changes.templateEncoding.
tracPassword String 2.4 Defines the Trac password for authentication into a private Trac installation.
User property is: changes.tracPassword.
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.
User property is: changes.tracUser.
url String 2.0-beta-2 Distribution URL of the artifact. This parameter will be passed to the template.
User property is: project.url.
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.
useJql boolean 2.10 Use the JIRA query language instead of the JIRA query based on HTTP parameters. From JIRA 5.1 and up only JQL is supported. JIRA 4.4 supports both JQL and URL parameter based queries. From 5.1.1 this is obsolete, since REST queries only use JQL.
Default value is: false.
User property is: changes.useJql.
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-".


User property is: changes.versionPrefix.
webPassword String 2.4 Defines the http password for basic authentication into the JIRA webserver.
User property is: changes.webPassword.
webUser String 2.4 Defines the http user for basic authentication into the JIRA webserver.
User property is: changes.webUser.
xmlPath File 2.0-beta-2 The path of the changes.xml file.
Default value is: ${basedir}/src/changes/changes.xml.

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

announcementDirectory:

Directory where the announcement file will be generated.
  • Type: java.io.File
  • Since: 2.10
  • Required: Yes
  • Default: ${project.build.directory}/announcement

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
  • User Property: changes.announcementFile

basedir:

The current project base directory.
  • Type: java.lang.String
  • Since: 2.1
  • Required: Yes
  • User Property: 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
  • User Property: 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
  • User Property: 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
  • User Property: generateJiraAnnouncement
  • Default: false

githubAPIPort:

The port of your github api domain. Only use if using github enterprise.
  • Type: int
  • Since: 2.9
  • Required: No
  • User Property: changes.githubAPIPort
  • Default: 80

githubAPIScheme:

The scheme of your github api domain. Only use if using github enterprise.
  • Type: java.lang.String
  • Since: 2.9
  • Required: No
  • User Property: changes.githubAPIScheme
  • Default: http

githubAPIServerId:

The settings.xml server id to be used to authenticate into github api domain. Only use if using github enterprise.
  • Type: java.lang.String
  • Since: 2.12
  • Required: No
  • Default: github

includeOpenIssues:

Boolean which says if we should include open github issues in the announcement.
  • Type: boolean
  • Since: 2.0-beta-2
  • Required: No
  • 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

jiraConnectionTimeout:

Defines the connection timeout in milliseconds when accessing JIRA's REST-API.

Might help when you have a lot of different resolutions in your JIRA instance.

  • Type: int
  • Since: 2.11
  • Required: No
  • User Property: changes.jiraConnectionTimeout
  • Default: 36000

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
  • User Property: 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
  • User Property: changes.jiraPassword

jiraReceiveTimout:

Defines the receive timeout in milliseconds when accessing JIRA's REST-API.

Might help when you have a lot of different resolutions in your JIRA instance.

  • Type: int
  • Since: 2.11
  • Required: No
  • User Property: changes.jiraReceiveTimout
  • Default: 32000

jiraUser:

Defines the JIRA username for authentication into a private JIRA installation.
  • Type: java.lang.String
  • Since: 2.1
  • Required: No
  • User Property: 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
  • User Property: changes.maxEntries
  • Default: 25

outputDirectory:

Deprecated. Starting with version 2.10 this parameter is no longer used. You must use announcementDirectory instead.
Directory where the announcement file will be generated.
  • Type: java.io.File
  • Since: 2.0-beta-2
  • Required: No

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
  • User Property: 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
  • User Property: 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
  • User Property: changes.statusIds
  • Default: Closed

template:

The Velocity template used to format the announcement.
  • Type: java.lang.String
  • Since: 2.0-beta-2
  • Required: Yes
  • User Property: 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
  • User Property: changes.templateDirectory
  • Default: org/apache/maven/plugin/announcement

templateEncoding:

The template encoding.
  • Type: java.lang.String
  • Since: 2.1
  • Required: No
  • User Property: 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
  • User Property: 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
  • User Property: 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
  • User Property: 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

useJql:

Use the JIRA query language instead of the JIRA query based on HTTP parameters. From JIRA 5.1 and up only JQL is supported. JIRA 4.4 supports both JQL and URL parameter based queries. From 5.1.1 this is obsolete, since REST queries only use JQL.
  • Type: boolean
  • Since: 2.10
  • Required: No
  • User Property: changes.useJql
  • Default: false

version:

Version of the artifact.
  • Type: java.lang.String
  • Since: 2.0-beta-2
  • Required: Yes
  • User Property: 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
  • User Property: changes.versionPrefix

webPassword:

Defines the http password for basic authentication into the JIRA webserver.
  • Type: java.lang.String
  • Since: 2.4
  • Required: No
  • User Property: changes.webPassword

webUser:

Defines the http user for basic authentication into the JIRA webserver.
  • Type: java.lang.String
  • Since: 2.4
  • Required: No
  • User Property: changes.webUser

xmlPath:

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