| ------ |
| Usage |
| ------ |
| Johnny R. Ruiz III |
| Allan Ramirez |
| Dennis Lundberg |
| ------ |
| 2011-05-31 |
| ------ |
| |
| ~~ Licensed to the Apache Software Foundation (ASF) under one |
| ~~ or more contributor license agreements. See the NOTICE file |
| ~~ distributed with this work for additional information |
| ~~ regarding copyright ownership. The ASF licenses this file |
| ~~ to you under the Apache License, Version 2.0 (the |
| ~~ "License"); you may not use this file except in compliance |
| ~~ with the License. You may obtain a copy of the License at |
| ~~ |
| ~~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~~ |
| ~~ Unless required by applicable law or agreed to in writing, |
| ~~ software distributed under the License is distributed on an |
| ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| ~~ KIND, either express or implied. See the License for the |
| ~~ specific language governing permissions and limitations |
| ~~ under the License. |
| |
| ~~ NOTE: For help with the syntax of this file, see: |
| ~~ http://maven.apache.org/doxia/references/apt-format.html |
| |
| |
| Usage |
| |
| This plugin is used to create a Changes Report, a JIRA Report and an |
| Announcement text file. It is also able to send the announcement via email. |
| |
| |
| *How to Generate the Changes Report |
| |
| In order to use this goal, simply create a <<<changes.xml>>> file in the <<<src/changes/>>> directory. |
| Here's an example of a typical <<<changes.xml>>>, showing the syntax: |
| |
| ------------------- |
| <document xmlns="http://maven.apache.org/changes/1.0.0" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://maven.apache.org/changes/1.0.0 http://maven.apache.org/xsd/changes-1.0.0.xsd"> |
| <properties> |
| <title>Changes Tester Project</title> |
| <author email="jruiz@exist.com">Johnny R. Ruiz III</author> |
| </properties> |
| <body> |
| <release version="1.1" date="2005-03-01" description="Subsequent release"> |
| <action dev="jruiz" type="add"> |
| Added additional documentation on how to configure the plugin. |
| </action> |
| <action dev="aramirez" type="fix" issue="MPJIRA-11"> |
| Enable retrieving component-specific issues. |
| </action> |
| <action dev="jruiz" type="remove" due-to="Allan Ramirez" due-to-email="aramirez@exist.com"> |
| The element type " link " must be terminated by the matching end-tag. |
| Deleted the erroneous code. |
| </action> |
| </release> |
| |
| <release version="1.0" date="2005-01-01" description="First release"> |
| <action dev="jruiz" type="update"> |
| Uploaded documentation on how to use the plugin. |
| </action> |
| </release> |
| </body> |
| </document> |
| ------------------- |
| |
| See the {{{./changes.html}Changes Reference}} for details regarding the |
| <<<\<release\>>>> and <<<\<action\>>>> elements and their attributes. |
| |
| To generate the Changes Report, insert the Changes Plugin in the |
| <<<\<reporting\>>>> section of your project's <<<pom.xml>>> |
| |
| ------------------- |
| <project> |
| ... |
| <reporting> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-changes-plugin</artifactId> |
| <version>${project.version}</version> |
| <reportSets> |
| <reportSet> |
| <reports> |
| <report>changes-report</report> |
| </reports> |
| </reportSet> |
| </reportSets> |
| </plugin> |
| </plugins> |
| </reporting> |
| ... |
| </project> |
| ------------------- |
| |
| and execute the <<<site>>> phase to generate the report. |
| |
| ------------------- |
| mvn site |
| ------------------- |
| |
| ** Linking to Your Issue Management System |
| |
| If you use the <<<issue>>> attribute in your <<<changes.xml>>> file and have |
| the <<<\<issueManagement\>>>> element configured in your <<<pom.xml>>>, the |
| report will contain links to the issues in your issue management system. |
| |
| Starting with version 2.4 the plugin comes pre-configured for a whole bunch of |
| different issue management systems. All you have to to is enter your issue |
| management system and the URL to it in your POM. It can look like this: |
| |
| ----- |
| <project> |
| ... |
| <issueManagement> |
| <system>JIRA</system> |
| <url>http://jira.company.com/</url> |
| </issueManagement> |
| ... |
| </project> |
| ----- |
| |
| If you have a previous configuration for <<<\<issueLinkTemplatePerSystem\>>>> |
| in your POM, you can probably throw that away when you start using version 2.4, |
| unless you use more than one issue management system. |
| |
| The following table shows the pre-configured issue management systems and the |
| templates they use to create links from your Changes Report directly to the |
| issues in your issue management system. |
| |
| *---------------+--------------------------------------------------------+ |
| | <<System>> | <<Issue Link Template>> | |
| *---------------+--------------------------------------------------------+ |
| | Bitbucket | %URL%/issue/%ISSUE% | |
| *---------------+--------------------------------------------------------+ |
| | Bugzilla | %URL%/show_bug.cgi?id=%ISSUE% | |
| *---------------+--------------------------------------------------------+ |
| | GitHub | %URL%/%ISSUE% | |
| *---------------+--------------------------------------------------------+ |
| | GoogleCode | %URL%/detail?id=%ISSUE% | |
| *---------------+--------------------------------------------------------+ |
| | JIRA | %URL%/%ISSUE% | |
| *---------------+--------------------------------------------------------+ |
| | Mantis | %URL%/view.php?id=%ISSUE% | |
| *---------------+--------------------------------------------------------+ |
| | MKS Integrity | %URL%/viewissue?selection=%ISSUE% | |
| *---------------+--------------------------------------------------------+ |
| | Redmine | %URL%/issues/show/%ISSUE% | |
| *---------------+--------------------------------------------------------+ |
| | Scarab | %URL%/issues/id/%ISSUE% | |
| *---------------+--------------------------------------------------------+ |
| | SourceForge | http://sourceforge.net/support/tracker.php?aid=%ISSUE% | |
| *---------------+--------------------------------------------------------+ |
| | SourceForge2 | %URL%/%ISSUE% | |
| *---------------+--------------------------------------------------------+ |
| | Trac | %URL%/ticket/%ISSUE% | |
| *---------------+--------------------------------------------------------+ |
| | Trackplus | %URL%/printItem.action?key=%ISSUE% | |
| *---------------+--------------------------------------------------------+ |
| | Tuleap | %URL%/?aid=%ISSUE% | |
| *---------------+--------------------------------------------------------+ |
| | YouTrack | %URL%/issue/%ISSUE% | |
| *---------------+--------------------------------------------------------+ |
| |
| If you use an issue management system other than the ones above, you need to |
| {{{./changes-report-mojo.html#issueLinkTemplatePerSystem}configure an issue |
| link template for it}}. |
| We would love to extend the table above with more issue management systems, |
| so if you have a working configuration that is not listed above, please tell |
| us about it by {{{./issue-tracking.html}creating an issue for it}}. |
| |
| <<Note:>> Make sure that your <<<\<issueManagement\>/\<url\>>>> is |
| correct. In particular, make sure that it has a trailing slash if it needs one. |
| The plugin can't add this for you, because it needs to handle different issue |
| management systems. If your issue management system is at |
| <<<http://www.company.com/bugzilla/>>> |
| the links will not work if you enter <<<http://www.company.com/bugzilla>>> |
| in your <<<pom.xml>>>. |
| |
| |
| *How to Generate the JIRA Report |
| |
| <<Note:>> To use the JIRA Report, the <<<\<issueManagement\>>>> section in |
| the <<<pom.xml>>> of your project must be configured. It might look something |
| like this: |
| |
| ------------------- |
| <project> |
| ... |
| <issueManagement> |
| <system>JIRA</system> |
| <url>https://issues.apache.org/jira/browse/MCHANGES</url> |
| </issueManagement> |
| ... |
| </project> |
| ------------------- |
| |
| To generate the JIRA Report, insert the Changes Plugin in the |
| <<<\<reporting\>>>> section of your project's <<<pom.xml>>> |
| |
| ------------------- |
| <project> |
| ... |
| <reporting> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-changes-plugin</artifactId> |
| <version>${project.version}</version> |
| <reportSets> |
| <reportSet> |
| <reports> |
| <report>jira-report</report> |
| </reports> |
| </reportSet> |
| </reportSets> |
| </plugin> |
| </plugins> |
| </reporting> |
| ... |
| </project> |
| ------------------- |
| |
| and execute the site goal to generate the report. |
| |
| ------------------- |
| mvn site |
| ------------------- |
| |
| For info on how to modify the JIRA Report see the |
| {{{./examples/customizing-jira-report.html}Customizing the JIRA Report}} |
| example. |
| |
| *How to Generate the GitHub Report |
| |
| <<Note:>> To use the GitHub Report, the <<<\<issueManagement\>>>> section in |
| the <<<pom.xml>>> of your project must be configured. It might look something |
| like this: |
| |
| ------------------- |
| <project> |
| ... |
| <issueManagement> |
| <system>GitHub</system> |
| <url>https://github.com/rails/rails/issues</url> |
| </issueManagement> |
| ... |
| </project> |
| ------------------- |
| |
| To generate the GitHub Report, insert the Changes Plugin in the |
| <<<\<reporting\>>>> section of your project's <<<pom.xml>>> |
| |
| ------------------- |
| <project> |
| ... |
| <reporting> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-changes-plugin</artifactId> |
| <version>${project.version}</version> |
| <reportSets> |
| <reportSet> |
| <reports> |
| <report>github-report</report> |
| </reports> |
| </reportSet> |
| </reportSets> |
| </plugin> |
| </plugins> |
| </reporting> |
| ... |
| </project> |
| ------------------- |
| |
| and execute the site goal to generate the report. |
| |
| ------------------- |
| mvn site |
| ------------------- |
| |
| For info on how to modify the JIRA Report see the |
| {{{./examples/configuring-github-report.html}Configuring the GitHub Report}} |
| example. |
| |
| *How to generate and send the Announcement via Email |
| |
| As usual we start by configuring your project's <<<pom.xml>>>. We add a basic |
| configuration for sending emails and specify the lucky recipients of the |
| announcement emails. |
| |
| For info on how to change the sender of the email see the |
| {{{./examples/specifying-mail-sender.html}Specifying the mail sender}} example. |
| |
| If you have customizations for JIRA that add additional issue types, |
| or if you are using an IMS that isn't fully-supported in this plugin, |
| you will need to configure any additional issue types here. |
| |
| For each issue type, you have to map it to one of three action types: |
| <add>, <fix>, or <update>. These terms are a bit arbitrary. By default, for JIRA, |
| <add> corresponds to 'New Feature', <fix> corresponds to 'Bug', and <update> |
| corresponds to 'Improvement'. |
| |
| ------------------- |
| <project> |
| ... |
| <build> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-changes-plugin</artifactId> |
| <version>${project.version}</version> |
| <configuration> |
| ... |
| <smtpHost>mail.yourhost.com</smtpHost> |
| <smtpPort implementation="java.lang.Integer">25</smtpPort> |
| <toAddresses> |
| <toAddress implementation="java.lang.String">someones@email.com</toAddress> |
| <toAddress implementation="java.lang.String">anothersomeone@email.com</toAddress> |
| </toAddresses> |
| ... |
| <issueTypes> |
| <add>Story</add> |
| <fix>Defect, Malfunction</fix> |
| </issueTypes> |
| ... |
| </configuration> |
| </plugin> |
| </plugins> |
| </build> |
| ... |
| </project> |
| ------------------- |
| |
| You can now generate the announcement by executing the command below: |
| |
| ------------------- |
| mvn changes:announcement-generate |
| ------------------- |
| |
| If you want to generate the announcement based on JIRA you need to |
| configure that in your <<<pom.xml>>>, like this: |
| |
| ------------------- |
| <project> |
| ... |
| <build> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-changes-plugin</artifactId> |
| <version>${project.version}</version> |
| <configuration> |
| ... |
| <issueManagementSystems> |
| <issueManagementSystem>JIRA</issueManagementSystem> |
| </issueManagementSystems> |
| ... |
| </configuration> |
| </plugin> |
| </plugins> |
| </build> |
| ... |
| </project> |
| ------------------- |
| |
| To generate the announcement based on <<both>> a <<<changes.xml>>> file and JIRA |
| you should configure your <<<pom.xml>>> like this: |
| |
| ------------------- |
| <project> |
| ... |
| <build> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-changes-plugin</artifactId> |
| <version>${project.version}</version> |
| <configuration> |
| ... |
| <issueManagementSystems> |
| <issueManagementSystem>changes.xml</issueManagementSystem> |
| <issueManagementSystem>JIRA</issueManagementSystem> |
| </issueManagementSystems> |
| ... |
| </configuration> |
| </plugin> |
| </plugins> |
| </build> |
| ... |
| </project> |
| ------------------- |
| |
| This is how you send an email with the generated announcement: |
| |
| ------------------- |
| mvn changes:announcement-mail |
| ------------------- |
