Built by Maven

changes:announcement-generate

Full name:

org.apache.maven.plugins:maven-changes-plugin:3.0.0-M1:announcement-generate

Description:

Goal which generates 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: ${project.build.directory}/announcement
<basedir> String 2.1 The current project base directory.
User Property: basedir
<developmentTeam> String - Name of the team that develops the artifact. This parameter will be passed to the template.
Default: ${project.name} team
User Property: changes.developmentTeam
<finalName> String - The name of the artifact to be used in the announcement.
Default: ${project.build.finalName}
User Property: changes.finalName
<maxEntries> int - The maximum number of issues to fetch from JIRA.
Default: 25
User Property: changes.maxEntries
<template> String - The Velocity template used to format the announcement.
Default: announcement.vm
User Property: changes.template
<templateDirectory> String - Directory that contains the template.

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


Default: org/apache/maven/plugins/changes/announcement
User Property: changes.templateDirectory
<version> String - Version of the artifact.
Default: ${project.version}
User Property: changes.version

Optional Parameters

Name Type Since Description
<announceParameters> Map<Object,Object> 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: 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.
<githubAPIServerId> String 2.12 The settings.xml server id to be used to authenticate into GitHub Api.
Since 3.x - only password item is used as authentication token with Authorization: Bearer YOUR-TOKEN Authenticating to the REST API
Default: github
<includeOpenIssues> boolean - Boolean which says if we should include open github issues in the announcement.
Default: false
<introduction> String - Short description or introduction of the released artifact. This parameter will be passed to the template.
Default: ${project.description}
<issueManagementSystems> List<String> 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<String,String> 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: 36000
User Property: changes.jiraConnectionTimeout
<jiraPassword> String 2.1 Defines the JIRA password for authentication into a private JIRA installation.
User Property: 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: 32000
User Property: changes.jiraReceiveTimout
<jiraServerId> String 3.0.0 The settings.xml server id to be used for authentication into a private JIRA installation.
User Property: changes.jiraServerId
<jiraUser> String 2.1 Defines the JIRA username for authentication into a private JIRA installation.
User Property: changes.jiraUser
<onlyCurrentVersion> boolean 3.0.0 If you only want to show issues from JIRA for the current version in the report. The current version being used is ${project.version} minus any "-SNAPSHOT" suffix.
Default: false
<resolutionIds> String - 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: Fixed
User Property: 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: false
User Property: announcement.runOnlyAtExecutionRoot
<statusIds> String - Include issues from JIRA with these status ids. Multiple status ids can be specified as a comma separated list of ids.
Default: Closed
User Property: changes.statusIds
<templateEncoding> String 2.1 The template encoding.
Default: ${project.build.sourceEncoding}
User Property: changes.templateEncoding
<tracPassword> String 2.4 Defines the Trac password for authentication into a private Trac installation.
User Property: changes.tracPassword
<tracQuery> String 2.4 Defines the Trac query for searching for tickets.
Default: order=id
<tracUser> String 2.4 Defines the Trac username for authentication into a private Trac installation.
User Property: changes.tracUser
<url> String - Distribution URL of the artifact. This parameter will be passed to the template.
User Property: project.url
<urlDownload> String - 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
Deprecated.
ignored; remove from your configs

Obsolete, since REST queries always use JQL.
Default: false
User Property: 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: changes.versionPrefix
<webPassword> String 2.4
Deprecated.
use jiraPassword or jiraServerId

Defines the http password for basic authentication into the JIRA webserver.
User Property: changes.webPassword
<webUser> String 2.4
Deprecated.
use jiraUser or jiraServerId

Defines the http user for basic authentication into the JIRA webserver.
User Property: changes.webUser
<xmlPath> File - The path of the changes.xml file.
Default: ${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<java.lang.Object, java.lang.Object>
  • 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
  • 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
  • Required: Yes
  • User Property: changes.finalName
  • Default: ${project.build.finalName}

<githubAPIServerId>

The settings.xml server id to be used to authenticate into GitHub Api.
Since 3.x - only password item is used as authentication token with Authorization: Bearer YOUR-TOKEN Authenticating to the REST API
  • 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
  • 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
  • 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<java.lang.String>
  • 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<java.lang.String, java.lang.String>
  • 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

<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

<jiraServerId>

The settings.xml server id to be used for authentication into a private JIRA installation.
  • Type: java.lang.String
  • Since: 3.0.0
  • Required: No
  • User Property: changes.jiraServerId

<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.
  • Type: int
  • Required: Yes
  • User Property: changes.maxEntries
  • Default: 25

<onlyCurrentVersion>

If you only want to show issues from JIRA for the current version in the report. The current version being used is ${project.version} minus any "-SNAPSHOT" suffix.
  • Type: boolean
  • Since: 3.0.0
  • Required: No
  • Default: false

<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
  • 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.
  • Type: java.lang.String
  • Required: No
  • User Property: changes.statusIds
  • Default: Closed

<template>

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

<useJql>

Deprecated.
ignored; remove from your configs

Obsolete, since REST queries always use JQL.
  • Type: boolean
  • Since: 2.10
  • Required: No
  • User Property: changes.useJql
  • Default: false

<version>

Version of the artifact.
  • Type: java.lang.String
  • 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>

Deprecated.
use jiraPassword or jiraServerId

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>

Deprecated.
use jiraUser or jiraServerId

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
  • Required: No
  • Default: ${basedir}/src/changes/changes.xml