changes:announcement-generate

Full name:

org.apache.maven.plugins:maven-changes-plugin:2.12.8: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.
<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/plugins/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.
<failOnError> boolean 2.0-beta-2 Mojo failure in case of exception when getting no release for supplied arguments. If false only a warning will be logged.
Default value is: true.
User property is: announcement.failOnError.
<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.
<generateJiraAnnouncement> Boolean 2.0-beta-2 Deprecated. Since version 2.4 this parameter has been deprecated. Please use the issueManagementSystems parameter instead.
User property is: generateJiraAnnouncement.
<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. The server's password field should contain a GitHub personal access token (OAuth2). Only use if using github enterprise or if personalToken is not set.
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.
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.
<personalToken> String 2.0-beta-2 Github personal token. If informed, it will take precedence for user and password associated with serverId which will be ignored.
<removeSnapshotSuffix> boolean 2.12.13 If "-SNAPSHOT" suffix should be removed when searching for issues.
Default value is: true.
User property is: changes.removeSnapshotSuffix.
<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

<failOnError>

Mojo failure in case of exception when getting no release for supplied arguments. If false only a warning will be logged.
  • Type: boolean
  • Since: 2.0-beta-2
  • Required: No
  • User Property: announcement.failOnError
  • Default: true

<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: java.lang.Boolean
  • Since: 2.0-beta-2
  • Required: No
  • User Property: generateJiraAnnouncement

<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. The server's password field should contain a GitHub personal access token (OAuth2). Only use if using github enterprise or if personalToken is not set.
  • 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: java.lang.Boolean
  • Since: 2.1
  • Required: No
  • User Property: changes.jiraMerge

<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

<personalToken>

Github personal token. If informed, it will take precedence for user and password associated with serverId which will be ignored.
  • Type: java.lang.String
  • Since: 2.0-beta-2
  • Required: No

<removeSnapshotSuffix>

If "-SNAPSHOT" suffix should be removed when searching for issues.
  • Type: boolean
  • Since: 2.12.13
  • Required: No
  • User Property: changes.removeSnapshotSuffix
  • Default: true

<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/plugins/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