issues-maven-plugin

Basic Configuration

The information on how to access the issue management server is usually specified in the issueManagement element within your POM.

<issueManagement>
  <system>bugzilla</system>
  <url>http://my.url.to/bugzilla</url>
</issueManagement>

For further information please refer to Issue Management.

The values may be overridden in the plugin's configuration using

This may be an option if you have to configure multiple issue management systems.

How to generate a reports

We provide detailed information for some different reports on individual pages. Please follow the links below for information how to configure for the different reports.

Tabular Report - a simple tabular report listing the queried bugs by their configured columns.
Release Notes - a standard release notes report requiring specific properties configured with Bugzilla.
Release Plan - a standard release plan report requiring specific properties configured with Bugzilla.
Keyword Reports - configurations of the tabular report to match specific keywords. Two examples are provided:
- Breaking News - listing of issues that break API or runtime behavior.
- New & Noteworthy - renders all issues tagged as 'New and Noteworthy'.
Multiple Reports - shows the configuration to create multiple reports at once.

Multi Projects

In multi projects it is common (and currently no way to change this) to generate one report for each sub project (module) and one report listing the issues of all projects.

In the parent module define the following in the properties section.

<issues-product>myProductName</issues-product>
<issues-component></issues-component>

In the submodules also specify the component:

<issues-product>myProductName</issues-product>
<issues-component>myComponentA</issues-component>

Use these properties to configure your maven-issue-plugin.

<plugin>
  <groupId>de.smartics.maven.plugin</groupId>
  <artifactId>issues-maven-plugin</artifactId>
  <configuration>
    ...
    <product>${issues-product}</product>
    <component>${issues-component}</component>
    ...
  </configuration>
  ...
</plugin>

Using named Queries

It is simple to launch reports using named queries. Simply state the name of the query (queryName) and the columns (columns and columnWidths) you want to display.

Please make sure to specify a unique id (id) for your report and a unique file name (outputName, without the file name extension). The description (description) is the short text that serves as an introduction to the report and the element noResultsDescription is shown in the report if no issue is selected by your query.

<reportSet>
  <id>myXReport</id>
  <reports>
    <report>bugzilla-issues-report</report>
  </reports>
  <configuration>
    <outputName>my-x-report</outputName>
    <title>My X-Report</title>
    <description>Lists X-Bugs.</description>
    <noResultsDescription>No X-Bugs found in this release.</noResultsDescription>

    <queryName>myXBugs</queryName>
    <columns>bug_id,short_desc</columns>
    <columnWidths>65,0</columnWidths>
  </configuration>
</reportSet>

All other query parameters (such as keywords, severity are not taken into account if the property queryName is specified.

Adding an Introduction

Sometimes you want to include some extra information on the start of the report that is more than just a simple paragraph of text you can provide by the description element.

Without any configuration simply add a file with a name following the given pattern:

{outputName}-{version}.xml

Place this file in the in the directory src/site/relnotes. For instance

src/site/relnotes/release-notes-report-1.0.0.xml

The contents of the file is expected to be valid XDoc. Any content within the body is rendered after the main heading. Since the main heading is a section you may want to use elements starting at subsection level (more than one subsection within the body is allowed for this purpose). The content may look like this:

<?xml version="1.0" encoding="UTF-8"?>
<document>
  <body>
    <subsection name="The first Release!">
      <p>
        This is the first release of the issues-plugin. <b>Enjoy it!</b>
      </p>
      <p>
        Please do not hesitate to send us your comments.
      </p>
    </subsection>
  </body>
</document>

Please note that the SNAPSHOT modifier to version numbers is ignored. So do not write release notes for snapshot versions.

Adding the Component Column

Per default the component information is set to the second column if the component is not already specified in the column list and the query does not explicitly specify one component as a query parameter (in which case the column would be redundant because every line in the table would have the same value).

If you do not want to use the default behavior and not render the component, set includeComponentAtIndex to -1.

<includeComponentAtIndex>-1</includeComponentAtIndex>

If you just want to alter the column index and fix the width of the column from standard 0 (zero lets the HTML renderer decide without specifying a width) to 150 use the following:

<includeComponentAtIndex>3</includeComponentAtIndex>
<includeComponentAtIndexColumnWidth>150</includeComponentAtIndexColumnWidth>

References to previous Reports

Per default links to previous reports are added at the bottom of each report.

The following report set definition illustrates how to generate one of the referenced reports. In this example the release notes for the versions 1.0.0 (included) and 2.0.0 (excluded) is generated. This additional report will be referenced by the current release notes report with the name release-notes-report.

<reportSet>
  <id>release-notes-report-1_x</id>
  <reports>
    <report>bugzilla-releasenotes-report</report>
  </reports>
  <configuration>
    <outputName>release-notes-report-1_x</outputName>
    <title>Release Notes Version 1.x</title>
    <versionRange>[1.0.0,2.0.0)</versionRange>
  </configuration>
</reportSet>

To be recognized as a previous report of another report the outputName must extend the later report's outputName. So if you define reports for previous versions of release-notes-report the outputName must use this prefix as in release-notes-report-1_x.

If you do not want to render links to previous reports, use

<referencePreviousReports>false</referencePreviousReports>

Only links to existing reports are rendered. The discovery of reports is solely based on the naming pattern of the output name.

To only include issues fixed and closed in the current version of the project (please note that the Target Milestone is required), set the currentReleaseVersionOnly property like this:

<currentReleaseVersionOnly>true</currentReleaseVersionOnly>

Activate Logging

The log level of the plugin can be set individually by the property logLevel.

<logLevel>FINEST</logLevel>

FINEST set the most verbose log level. INFO, WARNING and SEVERE are also supported. If no debug level is explicitly specified, Maven's debug level is used as default.

Tuning the Connection

If you encounter problems to log out from Bugzilla, consider using the property ignoreLogoutProblem. This will, as you already guessed, ignore any logout problem.

<ignoreLogoutProblem>true</ignoreLogoutProblem>

You can also set the retry count (maxRetries) and the idle time (timeout) between retries to control the access to the Bugzilla server via a slow or unreliable connection. Please refer to the report documentation for details.

Locale

Since the Bugzilla reports may be written in a different language than the locale used to generate the reports you may want to set the locale used in Bugzilla by the property locale.

If your site is generated in Spanish, but your issues are reported in English, set the following to use English as the report's language:

<locale>en</locale>

This will also use English for this particular report ignoring the locale used by the site plugin.

Skipping generation

Each report set can be configured to be skipped. This is for instance useful if you want to experiment with certain reports.

<skip>true</skip>

If you want to skip all reports you may use the system property issues.skip on the command line.

For skipping configured reports selectively, use the skipReports property.

<skipReports>
  <outputName>release-notes-report</outputName>
  <outputName>release-plan-report</outputName>
  <outputName>breaking-news</outputName>
  <outputName>new-and-noteworthy</outputName>
</skipReports>

Usage