------ 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 <<>> file in the <<>> directory. Here's an example of a typical <<>>, showing the syntax: ------------------- Changes Tester Project Johnny R. Ruiz III Added additional documentation on how to configure the plugin. Enable retrieving component-specific issues. The element type " link " must be terminated by the matching end-tag. Deleted the erroneous code. Uploaded documentation on how to use the plugin. ------------------- See the {{{./changes.html}Changes Reference}} for details regarding the <<<\>>> and <<<\>>> elements and their attributes. To generate the Changes Report, insert the Changes Plugin in the <<<\>>> section of your project's <<>> ------------------- ... org.apache.maven.plugins maven-changes-plugin ${project.version} changes-report ... ------------------- and execute the <<>> phase to generate the report. ------------------- mvn site ------------------- ** Linking to Your Issue Management System If you use the <<>> attribute in your <<>> file and have the <<<\>>> element configured in your <<>>, 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: ----- ... JIRA http://jira.company.com/ ... ----- If you have a previous configuration for <<<\>>> 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. *---------------+--------------------------------------------------------+ | <> | <> | *---------------+--------------------------------------------------------+ | 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% | *---------------+--------------------------------------------------------+ | 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}}. <> Make sure that your <<<\/\>>> 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 <<>> the links will not work if you enter <<>> in your <<>>. *How to Generate the JIRA Report <> To use the JIRA Report, the <<<\>>> section in the <<>> of your project must be configured. It might look something like this: ------------------- ... JIRA http://jira.codehaus.org/browse/MCHANGES ... ------------------- To generate the JIRA Report, insert the Changes Plugin in the <<<\>>> section of your project's <<>> ------------------- ... org.apache.maven.plugins maven-changes-plugin ${project.version} jira-report ... ------------------- 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 <> To use the GitHub Report, the <<<\>>> section in the <<>> of your project must be configured. It might look something like this: ------------------- ... GitHub https://github.com/rails/rails/issues ... ------------------- To generate the GitHub Report, insert the Changes Plugin in the <<<\>>> section of your project's <<>> ------------------- ... org.apache.maven.plugins maven-changes-plugin ${project.version} github-report ... ------------------- 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 <<>>. 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: , , or . These terms are a bit arbitrary. By default, for JIRA, corresponds to 'New Feature', corresponds to 'Bug', and corresponds to 'Improvement'. ------------------- ... org.apache.maven.plugins maven-changes-plugin ${project.version} ... mail.yourhost.com 25 someones@email.com anothersomeone@email.com ... Story Defect, Malfunction ... ... ------------------- 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 <<>>, like this: ------------------- ... org.apache.maven.plugins maven-changes-plugin ${project.version} ... JIRA ... ... ------------------- To generate the announcement based on <> a <<>> file and JIRA you should configure your <<>> like this: ------------------- ... org.apache.maven.plugins maven-changes-plugin ${project.version} ... changes.xml JIRA ... ... ------------------- This is how you send an email with the generated announcement: ------------------- mvn changes:announcement-mail -------------------