<?xml version="1.0"?>
<!-- 
/*
 * Copyright 2001-2004 The Apache Software Foundation.
 * 
 * Licensed 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.
 */
 -->

<document>

  <properties>
    <title>Maven Changes plugin</title>
    <author email="vmassol@apache.org">Vincent Massol</author>
  </properties>

  <body>
    <section name="Maven Changes plugin">
      <p>
        This plugin produces a changes report showing the differences 
        between different releases of the project using it.
      </p>
    </section>
    <section name="Using the plugin">
      <p>
        In order to use this plugin, simply create a <code>changes.xml</code>
        file in your <code>xdocs</code> directory. Here's an example of a
        typical <code>changes.xml</code>, showing the syntax:
      </p>
<source><![CDATA[
<document>
  <properties>
    <title>Page title</title>
    <author email="vmassol@apache.org">Vincent Massol</author>
  </properties>
  <body>

    <release version="2.0" date="in CVS">
      <action dev="vmassol" type="update">
        Blah blah.
      </action>              
    </release>

    <release version="1.0" date="2003-06-05">
      <action dev="vmassol" type="add">
        Added blah blah.
      </action>              
      <action dev="vmassol" type="fix" issues="JIRA-XXX">
        Corrected bug blah blah.
      </action>              
      <action dev="vmassol" type="remove" due-to="John Doe" due-to-email="john@doe.com">
        Removed blah blah.
      </action>              
    </release>
  </body>
</document>
]]></source>     

      <p>
        A live Changes example report can be found 
        <a href="http://maven.apache.org/reference/plugins/changes/changes-report.html">here</a>.
      </p>

      <p>
        The following attributes are supported for the <code>&lt;release&gt;</code>
        element:
      </p>      

      <table>
        <tr>
          <th>Attribute name</th>
          <th>Description</th>
          <th>Required?</th>
        </tr>
        <tr>
          <td>version</td>
          <td>
            Name of the version for which to describe the changes. For each 
            change, add a nested <code>&lt;action&gt;</code> element as
            described below.
          </td>
          <td>yes</td>
        </tr>
        <tr>
          <td>date</td>
          <td>
            Date at which the version was released. You can use a free form
            comment such as "in CVS" for unreleased versions.
          </td>
          <td>yes</td>
        </tr>
      </table>
      
      <p>
        The following attributes are supported for the <code>&lt;action&gt;</code>
        element:
      </p>      

      <table>
        <tr>
          <th>Attribute name</th>
          <th>Description</th>
          <th>Required?</th>
        </tr>
        <tr>
          <td>dev</td>
          <td>
            Name of developer who committed the change. This must be the name
            of the developer as described in the <code>developers</code> 
            section of the POM (<code>project.xml</code> file).
          </td>
          <td>yes</td>
        </tr>
        <tr>
          <td>type</td>
          <td>
            Type of change. There are four valid values:
            <code>add</code>, <code>fix</code>, <code>remove</code>,
            <code>update</code>.
          </td>
          <td>yes</td>
        </tr>
        <tr>
          <td>issue</td>
          <td>
            Id of the issue related to this change. This is the id in your
            bug tracking system. The Changes plugin will generate a URL out 
            of this id. The URL is constructed by using the 
            <code>maven.changes.issue.template</code> property. See the
            <a href="properties.html">page</a> for more details.
          </td>
          <td>no</td>
        </tr>
        <tr>
          <td>due-to</td>
          <td>
            Name of the person to be credited for this change. To be used
            when a patch is submitted by a non-committer.
          </td>
          <td>no</td>
        </tr>
        <tr>
          <td>due-to-email</td>
          <td>
            Email of the person to be credited for this change.
          </td>
          <td>no</td>
        </tr>
      </table>

    </section>
 </body>
</document>
