This is an automated email from the ASF dual-hosted git repository.

slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-changes-plugin.git


The following commit(s) were added to refs/heads/master by this push:
     new 5b3a90c  Refresh the site documentation and README
5b3a90c is described below

commit 5b3a90ce71c06d51cf73a500341468500d8e4b58
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Wed Nov 18 07:32:33 2026 +0000

    Refresh the site documentation and README
---
 README.md                                          | 115 ++++++---------
 src/site/changes/sample-changes.xml                |   2 +-
 .../examples/alternate-changes-xml-location.md.vm  |   5 +-
 .../examples/changes-file-validation.md.vm         |   7 +-
 .../markdown/examples/check-changes-file.md.vm     |   4 +-
 .../examples/configuring-github-report.md.vm       |  30 ++--
 .../examples/configuring-trac-report.md.vm         |  35 ++---
 .../examples/customizing-jira-report.md.vm         |  25 +++-
 .../examples/include-announcement-file.md.vm       |   3 +-
 .../markdown/examples/smtp-authentication.md.vm    |  12 +-
 .../markdown/examples/specifying-mail-sender.md.vm |   4 +-
 .../using-a-custom-announcement-template.md.vm     |  17 ++-
 src/site/markdown/faq.md                           |  31 ++--
 src/site/markdown/index.md                         | 114 ++++++++++----
 src/site/markdown/usage.md.vm                      | 164 +++++++++++----------
 src/site/markdown/using-changes-xsd.md             |   7 +-
 src/site/site.xml                                  |  13 +-
 17 files changed, 319 insertions(+), 269 deletions(-)

diff --git a/README.md b/README.md
index f861da9..d58eed5 100644
--- a/README.md
+++ b/README.md
@@ -14,70 +14,51 @@
  See the License for the specific language governing permissions and
  limitations under the License.
 -->
-Contributing to [Apache Maven Changes 
Plugin](https://maven.apache.org/plugins/maven-changes-plugin/)
-======================
-
-[![Apache License, Version 2.0, January 
2004](https://img.shields.io/github/license/apache/maven.svg?label=License)][license]
-[![Maven 
Central](https://img.shields.io/maven-central/v/org.apache.maven.plugins/maven-changes-plugin.svg?label=Maven%20Central)](https://search.maven.org/artifact/org.apache.maven.plugins/maven-changes-plugin)
-[![Jenkins 
Status](https://img.shields.io/jenkins/s/https/ci-maven.apache.org/job/Maven/job/maven-box/job/maven-changes-plugin/job/master.svg?)][build]
-[![Jenkins 
tests](https://img.shields.io/jenkins/t/https/ci-maven.apache.org/job/Maven/job/maven-box/job/maven-changes-plugin/job/master.svg?)][test-results]
-
-
-You have found a bug, or you have an idea for a cool new feature? Contributing
-code is a great way to give something back to the open source community. Before
-you dig right into the code, there are a few guidelines that we need
-contributors to follow so that we can have a chance of keeping on top of
-things.
-
-Getting Started
----------------
-
-+ Make sure you have a [GitHub account](https://github.com/signup/free).
-+ If you're planning to implement a new feature, it makes sense to discuss 
your changes 
-  on the [dev list][ml-list] first. 
-  This way you can make sure you're not wasting your time on something that 
isn't 
-  considered to be in Apache Maven's scope.
-+ Submit a ticket for your issue, assuming one does not already exist.
-  + Clearly describe the issue, including steps to reproduce when it is a bug.
-  + Make sure you fill in the earliest version that you know has the issue.
-+ Fork the repository on GitHub.
-
-Making and Submitting Changes
---------------
-
-We accept Pull Requests via GitHub. The [developer mailing list][ml-list] is 
the
-main channel of communication for contributors.  
-There are some guidelines which will make applying PRs easier for us:
-+ Create a topic branch from where you want to base your work (this is usually 
the master branch).
-  Push your changes to a topic branch in your fork of the repository.
-+ Make commits of logical units.
-+ Respect the original code style: by using the same [codestyle][code-style],
-  patches should only highlight the actual difference, not being disturbed by 
any formatting issues:
-  + Only use spaces for indentation.
-  + Create minimal diffs - disable on save actions like reformat source code 
or organize imports. 
-    If you feel the source code should be reformatted, create a separate PR 
for this change.
-  + Check for unnecessary whitespace with `git diff --check` before committing.
-+ Make sure you have added the necessary tests (JUnit/IT) for your changes.
-+ Run all the tests with `mvn -Prun-its verify` to assure nothing else was 
accidentally broken.
-+ Submit a pull request to the repository in the Apache organization.
-
-If you plan to contribute on a regular basis, please consider filing a 
[contributor license agreement][cla].
-
-Additional Resources
---------------------
-
-+ [Contributing 
patches](https://maven.apache.org/guides/development/guide-maven-development.html#Creating_and_submitting_a_patch)
-+ [Contributor License Agreement][cla]
-+ [General GitHub documentation](https://help.github.com/)
-+ [GitHub pull request 
documentation](https://help.github.com/send-pull-requests/)
-+ [Apache Maven X Account](https://x.com/ASFMavenProject)
-+ [Apache Maven Bluesky Account](https://bsky.app/profile/maven.apache.org)
-+ [Apache Maven Mastodon 
Account](https://mastodon.social/deck/@[email protected])
-
-[license]: https://www.apache.org/licenses/LICENSE-2.0
-[ml-list]: https://maven.apache.org/mailing-lists.html
-[code-style]: https://maven.apache.org/developers/conventions/code.html
-[cla]: https://www.apache.org/licenses/#clas
-[maven-wiki]: https://cwiki.apache.org/confluence/display/MAVEN/Index
-[test-results]: 
https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-changes-plugin/job/master/lastCompletedBuild/testReport/
-[build]: 
https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-changes-plugin/job/master/
+
+# Apache Maven Changes Plugin
+
+[![Apache License, Version 2.0, January 
2004](https://img.shields.io/github/license/apache/maven.svg?label=License)](https://www.apache.org/licenses/LICENSE-2.0)
+[![Maven 
Central](https://img.shields.io/maven-central/v/org.apache.maven.plugins/maven-changes-plugin.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/org.apache.maven.plugins/maven-changes-plugin)
+[![Verify](https://github.com/apache/maven-changes-plugin/actions/workflows/maven-verify.yml/badge.svg)](https://github.com/apache/maven-changes-plugin/actions/workflows/maven-verify.yml)
+
+Tells your users what changed between releases. The plugin reads the changes 
from a `changes.xml` file in the
+project or from an issue tracker (JIRA, GitHub or Trac), renders them as site 
reports, and generates a release
+announcement that it can also send by email.
+
+```shell
+mvn changes:changes                 # report from src/changes/changes.xml
+mvn changes:github-changes          # report from the GitHub issues in 
<issueManagement>
+mvn changes:changes-validate        # validate changes.xml against its schema
+mvn changes:announcement-generate   # write target/announcement/announcement.vm
+```
+
+The plugin requires Maven 3.9.0 or later and Java 8 or later.
+
+- Documentation: <https://maven.apache.org/plugins/maven-changes-plugin/>
+- Issues: <https://github.com/apache/maven-changes-plugin/issues>
+- Mailing lists: <https://maven.apache.org/mailing-lists.html>
+
+## Build
+
+```shell
+mvn verify
+```
+
+Integration tests run with the `run-its` profile. The JIRA, GitHub and mail 
tests use local mock servers:
+
+```shell
+mvn -Prun-its verify
+```
+
+Build the site with the sample reports:
+
+```shell
+mvn install -DskipTests
+mvn site -Preporting
+```
+
+## Contributing
+
+Open an issue or a pull request on GitHub. Before you push, run `mvn 
spotless:apply` and `mvn -Prun-its verify`. Larger
+changes are best discussed on the [developer mailing 
list](https://maven.apache.org/mailing-lists.html) first. See
+the [guide to helping with 
Maven](https://maven.apache.org/guides/development/guide-helping.html) for more.
diff --git a/src/site/changes/sample-changes.xml 
b/src/site/changes/sample-changes.xml
index 879bd2d..4394c6f 100644
--- a/src/site/changes/sample-changes.xml
+++ b/src/site/changes/sample-changes.xml
@@ -18,7 +18,7 @@ under the License.
 -->
 <document xmlns="http://maven.apache.org/changes/2.0.0";
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
-          xsi:schemaLocation="http://maven.apache.org/changes/2.0.0 
http://maven.apache.org/xsd/changes-2.0.0.xsd";>
+          xsi:schemaLocation="http://maven.apache.org/changes/2.0.0 
https://maven.apache.org/xsd/changes-2.0.0.xsd";>
   <properties>
     <title>Sample Changes Report: Title</title>
     <author email="[email protected]">Johnny R. Ruiz III</author>
diff --git a/src/site/markdown/examples/alternate-changes-xml-location.md.vm 
b/src/site/markdown/examples/alternate-changes-xml-location.md.vm
index e3202a6..bd0a9f0 100644
--- a/src/site/markdown/examples/alternate-changes-xml-location.md.vm
+++ b/src/site/markdown/examples/alternate-changes-xml-location.md.vm
@@ -26,9 +26,10 @@ under the License.
 
 # Alternate Location for the `changes.xml` File
 
-**Note:** Unless you have a specific reason to have your `changes.xml` file in 
a different location, we advice you to put it in the default location 
`${esc.d}{basedir}/src/changes/changes.xml`. If nothing else, it saves you from 
having to configure it.
+**Note:** Unless you have a specific reason to have your `changes.xml` file in 
a different location, we advise you to put it in the default location 
`${esc.d}{basedir}/src/changes/changes.xml`. If nothing else, it saves you from 
having to configure it.
 
-If you _really_ want to have your `changes.xml` in another location than the 
default location, you can do this by configuring your `pom.xml`. In this 
example we want to use the file `${esc.d}{basedir}/src/site/changes.xml`:
+If you want to have your `changes.xml` in another location, set `<xmlPath>` in 
your `pom.xml`. The goals
+`changes-validate`, `changes-check` and `announcement-generate` have the same 
parameter. In this example we want to use the file 
`${esc.d}{basedir}/src/site/changes.xml`:
 
 ```xml
 <project>
diff --git a/src/site/markdown/examples/changes-file-validation.md.vm 
b/src/site/markdown/examples/changes-file-validation.md.vm
index 9720859..b60aae1 100644
--- a/src/site/markdown/examples/changes-file-validation.md.vm
+++ b/src/site/markdown/examples/changes-file-validation.md.vm
@@ -26,7 +26,12 @@ under the License.
 
 # Validate Your changes.xml File
 
-Since 2.1, a [goal](../changes-validate-mojo.html) is provided to validate 
your `changes.xml` file.
+The [changes-validate](../changes-validate-mojo.html) goal validates your 
`changes.xml` file against the
+[XML schema](../using-changes-xsd.html). You can also run it from the command 
line:
+
+```
+mvn changes:changes-validate
+```
 
 You can attach this goal to the `pre-site` phase if you want the validation to 
be performed automatically when you generate the site.
 
diff --git a/src/site/markdown/examples/check-changes-file.md.vm 
b/src/site/markdown/examples/check-changes-file.md.vm
index 4f7599b..1f7777d 100644
--- a/src/site/markdown/examples/check-changes-file.md.vm
+++ b/src/site/markdown/examples/check-changes-file.md.vm
@@ -26,7 +26,9 @@ under the License.
 
 # Check Your changes.xml File
 
-Since version 2.4 this plugin has a [goal](../changes-check-mojo.html) that 
checks that your `changes.xml` file has a valid release date.
+The [changes-check](../changes-check-mojo.html) goal checks that your 
`changes.xml` file has a release for the
+current project version and that its release date is valid. Set 
`<skipSnapshots>` to `true` to skip the check for
+`-SNAPSHOT` versions.
 
 You can attach this goal to the `verify` phase if you want the check to be 
performed automatically when you build the project.
 
diff --git a/src/site/markdown/examples/configuring-github-report.md.vm 
b/src/site/markdown/examples/configuring-github-report.md.vm
index 75dd7ac..b3c02b7 100644
--- a/src/site/markdown/examples/configuring-github-report.md.vm
+++ b/src/site/markdown/examples/configuring-github-report.md.vm
@@ -26,17 +26,21 @@ under the License.
 
 # Configuring the GitHub Report
 
-**Note:** See the [goal documentation](../github-changes-mojo.html) for 
detailed info on which feature was added in which version.
+The `github-changes` report reads the issues of the repository named in 
`<issueManagement>/<url>`, which must look
+like `https://github.com/OWNER/REPO/issues/`. See the [goal 
documentation](../github-changes-mojo.html) for all
+parameters.
 
 Using GitHub Enterprise
 -----------------------
 
-Additional configurations are not needed. Address of your **GitHub** instance 
will be taken from `project -> issueManagement -> url`
+No additional configuration is needed. The address of your **GitHub** instance 
is taken from
+`<issueManagement>/<url>` in your POM.
 
 Authenticating to the GitHub REST API
 -------------------------------------
 
-If you are using GitHub Enterprise or you want to authenticate to GitHub, 
configure the server in settings.xml like so:
+Anonymous requests to the GitHub REST API have a low rate limit. If you are 
using GitHub Enterprise or you want to
+authenticate to GitHub, configure the server in `settings.xml` like so:
 
 ```xml
 <settings>
@@ -51,20 +55,22 @@ If you are using GitHub Enterprise or you want to 
authenticate to GitHub, config
 </settings>
 ```
 
-Only the `password` item is used as your token for `Authorization: Bearer 
YOUR-TOKEN`
+Only the `password` item is used, as the token in `Authorization: Bearer 
YOUR-TOKEN`. It can be
+[encrypted](https://maven.apache.org/guides/mini/guide-encryption.html).
 
 The default serverId is `github`. You can change it by setting the 
`<githubAPIServerId>` configuration parameter.
 
-[Authenticating to the REST 
API](https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api)
+See [Authenticating to the REST 
API](https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api)
+in the GitHub documentation.
 
 Filtering Issues
 ----------------
 
-We'll start off by creating a GitHub Report for one or more versions of your 
project. There are two ways to do this.
+By default the report includes open and closed issues, but only issues that 
have a milestone.
 
 #[[### Only include closed issues]]#
 
-If you only want to include closed issues in your report make sure to 
configure the includeOpenIssues to false in your configuration, which is true 
by default.
+If you only want to include closed issues in your report, set 
`<includeOpenIssues>` to `false`. It is `true` by default.
 
 ```xml
 <project>
@@ -88,7 +94,8 @@ If you only want to include closed issues in your report make 
sure to configure
 
 #[[### Include issues without milestones]]#
 
-If you only want to include issues that do not have a milestone attached to 
them in your report make sure to configure the onlyMilestoneIssues to false in 
your configuration, which is true by default.
+If you also want to include issues that do not have a milestone attached to 
them, set `<onlyMilestoneIssues>` to
+`false`. It is `true` by default.
 
 ```xml
 <project>
@@ -112,7 +119,7 @@ If you only want to include issues that do not have a 
milestone attached to them
 
 #[[### Using the current version]]#
 
-If you are lazy and only ever want the latest release in you GitHub Report, 
you can use the `<onlyCurrentVersion>` configuration parameter. It will take 
the version from your project's POM and try to match it against the milestone 
title of the GitHub issues.
+If you only ever want the current release in your GitHub Report, you can use 
the `<onlyCurrentVersion>` configuration parameter. It will take the version 
from your project's POM and try to match it against the milestone title of the 
GitHub issues.
 
 Once you have configured this, you can forget about it, as it updates itself 
when you change the version number in your POM.
 
@@ -141,7 +148,8 @@ Once you have configured this, you can forget about it, as 
it updates itself whe
 Selecting columns
 -----------------
 
-You can select which columns to include in the report.
+You can select which columns to include in the report. Valid columns for 
GitHub are `Assignee`, `Created`,
+`Fix Version`, `Id`, `Reporter`, `Status`, `Summary`, `Type` and `Updated`.
 
 ```xml
 <project>
@@ -153,7 +161,7 @@ You can select which columns to include in the report.
         <artifactId>maven-changes-plugin</artifactId>
         <version>${project.version}</version>
         <configuration>
-          <columnNames>Type,Key,Summary,Assignee,Status,Fix 
Version</columnNames>
+          <columnNames>Type,Id,Summary,Assignee,Status,Fix 
Version</columnNames>
         </configuration>
         ...
       </plugin>
diff --git a/src/site/markdown/examples/configuring-trac-report.md.vm 
b/src/site/markdown/examples/configuring-trac-report.md.vm
index e8d0ed2..c48a591 100644
--- a/src/site/markdown/examples/configuring-trac-report.md.vm
+++ b/src/site/markdown/examples/configuring-trac-report.md.vm
@@ -26,27 +26,31 @@ under the License.
 
 # Configuring the Trac Report
 
+**Note:** The Trac integration is deprecated and prepared for removal in the 
next major version due to lack of
+maintainers.
+
 Configuring your Trac instance
 ------------------------------
 
-The plugin needs to be told details of your Trac installation so that it can 
connect and query the open tickets. The Trac installation needs to be 
accessible via no authentication, basic authentication or NTLM authentication. 
If you've used form authentication then you are out of luck.
+The plugin needs to be told details of your Trac installation so that it can 
connect and query the open tickets. The Trac installation needs to be 
accessible via no authentication, basic authentication or NTLM authentication.
+Form-based authentication is not supported.
 
 Your Trac installation needs to have the [XML-RPC 
plugin](https://trac-hacks.org/wiki/XmlRpcPlugin) installed and working for 
this plugin to be able to read the tickets.
 
 #[[### Basic Report Configuration]]#
 
-The most basic report configuration is read from the `<issueManagement>` 
section of your POM. This should work with no additional configuration, but by 
default all ticket will be listed
+The most basic report configuration is read from the `<issueManagement>` 
section of your POM. This works with no additional configuration, but by 
default all tickets are listed.
 
 ```xml
   <issueManagement>
     <system>trac</system>
-    <url>http://mytracserver.local/trac/MYPROJECT/</url>
+    <url>https://trac.example.com/trac/MYPROJECT/</url>
   </issueManagement>
 ```
 
 #[[### Configuring a Custom Query]]#
 
-The exact query can configured in the `<query>` element. See 
[TracQuery](https://trac.edgewall.org/wiki/TracQuery) for the exact syntax.
+The exact query can be configured in the `<query>` element. See 
[TracQuery](https://trac.edgewall.org/wiki/TracQuery) for the exact syntax.
 
 ```xml
   ...
@@ -91,24 +95,5 @@ If you have your Trac sitting behind Apache on Windows with 
mod_sspi doing authe
 
 #[[### Using custom encoding]]#
 
-If you have to support non-western encodings, then specify an 
`<outputEncoding>` in the configuration.
-
-```xml
-<project>
-  ...
-  <reporting>
-    <plugins>
-      <plugin>
-        <groupId>org.apache.maven.plugins</groupId>
-        <artifactId>maven-changes-plugin</artifactId>
-        <version>${project.version}</version>
-        <configuration>
-          ...
-          <outputEncoding>Windows-31J</outputEncoding>
-        </configuration>
-      </plugin>
-    </plugins>
-  </reporting>
-  ...
-</project>
-```
+The report has no encoding parameter of its own. It is written in the output 
encoding of the site, which you set
+with the `outputEncoding` parameter of the [Maven Site 
Plugin](https://maven.apache.org/plugins/maven-site-plugin/site-mojo.html).
diff --git a/src/site/markdown/examples/customizing-jira-report.md.vm 
b/src/site/markdown/examples/customizing-jira-report.md.vm
index 0a32cb9..883b38e 100644
--- a/src/site/markdown/examples/customizing-jira-report.md.vm
+++ b/src/site/markdown/examples/customizing-jira-report.md.vm
@@ -26,7 +26,9 @@ under the License.
 
 # Customizing the JIRA Report
 
-**Note:** Most of the features used in this document were introduced in 
version **2.0** of the Changes Plugin. See the [goal 
documentation](../jira-changes-mojo.html) for detailed info on which feature 
was added in which version.
+The `jira-changes` report reads issues through the JIRA REST API. See the 
[goal documentation](../jira-changes-mojo.html)
+for all parameters. For a private JIRA instance, put the credentials in a 
`<server>` of your `settings.xml` and refer
+to it with `<jiraServerId>`.
 
 Selecting version(s)
 --------------------
@@ -35,7 +37,8 @@ We'll start off by creating a JIRA Report for one or more 
versions of your proje
 
 #[[### Using fix version id(s)]]#
 
-This is the manual way of doing it. You specify one or more fix version ids, 
separated by commas. The version ids are usually five digit numbers, but that 
depends on your JIRA installation.
+This is the manual way of doing it. You specify one or more fix versions, 
separated by commas, either by name or by
+JIRA's internal version id.
 
 The good thing about this method is that you can specify exactly which 
versions you want, but you have to remember to update your configuration for 
every new release that you want to include in the report.
 
@@ -49,7 +52,7 @@ The good thing about this method is that you can specify 
exactly which versions
         <artifactId>maven-changes-plugin</artifactId>
         <version>${project.version}</version>
         <configuration>
-          <fixVersionIds>13722,12515</fixVersionIds>
+          <fixVersionIds>2.12,2.12.1</fixVersionIds>
         </configuration>
         ...
       </plugin>
@@ -61,7 +64,7 @@ The good thing about this method is that you can specify 
exactly which versions
 
 #[[### Using the current version]]#
 
-If you are lazy and only ever want the latest release in you JIRA Report, you 
can use the `<onlyCurrentVersion>` configuration parameter. It will take the 
version from your project's POM and try to match it against the "Fix for" 
version of the JIRA issues.
+If you only ever want the current release in your JIRA Report, you can use the 
`<onlyCurrentVersion>` configuration parameter. It will take the version from 
your project's POM and try to match it against the "Fix for" version of the 
JIRA issues.
 
 Once you have configured this, you can forget about it, as it updates itself 
when you change the version number in your POM.
 
@@ -90,7 +93,9 @@ Once you have configured this, you can forget about it, as it 
updates itself whe
 Selecting columns
 -----------------
 
-If you are a fan of the Issue Navigator in JIRA, you are going to love this. 
You can select which columns to include in the report and also specify in which 
way the issues are sorted.
+You can select which columns to include in the report and also specify in 
which way the issues are sorted. Valid
+columns for JIRA are `Assignee`, `Component`, `Created`, `Fix Version`, `Id`, 
`Key`, `Priority`, `Reporter`,
+`Resolution`, `Status`, `Summary`, `Type`, `Updated` and `Version`.
 
 In this example we have selected a couple of extra columns, that are not 
included by default. We want the issues sorted by `Type` first and by `Key` 
secondly. The keys will be sorted in descending order thanks to the `DESC` 
marker. Normally they are sorted in ascending order.
 
@@ -150,9 +155,13 @@ You can also filter by `<component>` and `<priorityIds>`. 
See the [goal document
 
 #[[### Using JIRA syntax]]#
 
-Another way to filter and sort issues is to configure the plugin using a JIRA 
syntaxed filter. You can grab this from the URL if you filter and sort issues 
in the Issue Navigator in JIRA. Just remember that you have to escape the 
ampersand (&amp;) characters, when you put them into the XML based POM.
+Another way to filter and sort issues is to give the plugin a complete 
[JQL](https://support.atlassian.com/jira-service-management-cloud/docs/use-advanced-search-with-jira-query-language-jql/)
+query in `<filter>`. You can copy it from the advanced search in JIRA. The 
query replaces everything the plugin would
+otherwise build, including the project, the version and the other filter 
parameters above, so it must name the project
+itself. Remember to escape `&`, `<` and `>` characters when you put them into 
the XML based POM.
 
-In this example we are filtering out issues with _Fixed_ as resolution and 
sorting them by _type_, in ascending order.
+In this example we are only including issues with _Fixed_ as resolution and 
sorting them by _type_, in ascending
+order.
 
 ```xml
 <project>
@@ -164,7 +173,7 @@ In this example we are filtering out issues with _Fixed_ as 
resolution and sorti
         <artifactId>maven-changes-plugin</artifactId>
         <version>${project.version}</version>
         <configuration>
-          
<filter>resolution=1&amp;sorter/field=issuetype&amp;sorter/order=ASC</filter>
+          <filter>project = MCHANGES AND fixVersion = 2.12.1 AND resolution = 
Fixed ORDER BY issuetype ASC</filter>
         </configuration>
         ...
       </plugin>
diff --git a/src/site/markdown/examples/include-announcement-file.md.vm 
b/src/site/markdown/examples/include-announcement-file.md.vm
index 9f19de3..0b35411 100644
--- a/src/site/markdown/examples/include-announcement-file.md.vm
+++ b/src/site/markdown/examples/include-announcement-file.md.vm
@@ -26,7 +26,8 @@ under the License.
 
 # Include an Announcement File in Your Packaging
 
-Since version 2.4 this plugin has options that allows you to put the generated 
announcement file anywhere you like. This makes it possible to include the 
generated announcement in your packaging.
+The `announcement-generate` goal can put the generated announcement file 
anywhere you like. This makes it possible
+to include the generated announcement in your packaging.
 
 Configuring the Plugin
 ----------------------
diff --git a/src/site/markdown/examples/smtp-authentication.md.vm 
b/src/site/markdown/examples/smtp-authentication.md.vm
index 4b1c872..79a3188 100644
--- a/src/site/markdown/examples/smtp-authentication.md.vm
+++ b/src/site/markdown/examples/smtp-authentication.md.vm
@@ -26,9 +26,10 @@ under the License.
 
 # SMTP Authentication
 
-If the SMTP host needs authentication, you can provide your `<username>` and 
`<password>` in the `<configuration>` section:
+If the SMTP host needs authentication, you can provide your `<username>` and 
`<password>` in the `<configuration>`
+section. Use `<sslMode>` for SMTPS or `<startTls>` for STARTTLS:
 
-```
+```xml
 <project>
   ...
   <build>
@@ -38,9 +39,10 @@ If the SMTP host needs authentication, you can provide your 
`<username>` and `<p
         <artifactId>maven-changes-plugin</artifactId>
         <version>${project.version}</version>
         <configuration>
-          <smtpHost>mail.yourhost.com</smtpHost>
-          <smtpPort implementation="java.lang.Integer">25</smtpPort>
-          <username>[email protected]</username>
+          <smtpHost>mail.example.com</smtpHost>
+          <smtpPort>587</smtpPort>
+          <startTls>true</startTls>
+          <username>[email protected]</username>
           <password>somepassword</password>
           ...
         </configuration>
diff --git a/src/site/markdown/examples/specifying-mail-sender.md.vm 
b/src/site/markdown/examples/specifying-mail-sender.md.vm
index 59b4d1f..099626c 100644
--- a/src/site/markdown/examples/specifying-mail-sender.md.vm
+++ b/src/site/markdown/examples/specifying-mail-sender.md.vm
@@ -40,7 +40,7 @@ To specify which developer is used to send the announcement, 
simply specify the
     <developer>
       <id>jsmith</id>
       <name>John Smith</name>
-      <email>[email protected]</email>
+      <email>[email protected]</email>
     </developer>
     ...
   </developers>
@@ -86,7 +86,7 @@ If you want to specify the sender explicitly and not rely on 
the `developers` se
         <configuration>
           <mailSender>
             <name>Release Notification</name>
-            <email>[email protected]</email>
+            <email>[email protected]</email>
           </mailSender>
         </configuration>
       </plugin>
diff --git 
a/src/site/markdown/examples/using-a-custom-announcement-template.md.vm 
b/src/site/markdown/examples/using-a-custom-announcement-template.md.vm
index 9155c9f..8579168 100644
--- a/src/site/markdown/examples/using-a-custom-announcement-template.md.vm
+++ b/src/site/markdown/examples/using-a-custom-announcement-template.md.vm
@@ -31,9 +31,9 @@ The `announcement-generate` goal uses a 
[Velocity](https://velocity.apache.org/)
 Configuring the Plugin
 ----------------------
 
-First you must configure the plugin and tell it where your template is. In 
this example we want to use the template 
`${esc.d}{basedir}/src/main/resources/our-announcements/my-announcement.vm`.
+First you must configure the plugin and tell it where your template is. In 
this example we want to use the template 
`${esc.d}{basedir}/src/announcement/my-announcement.vm`. A directory outside 
`src/main/resources` keeps the template out of your JAR file.
 
-**Note:** The `<templateDirectory>` must be a subdirectory of 
`${esc.d}{basedir}/src/main/resources/`.
+**Note:** The `<templateDirectory>` is relative to the project base directory, 
`${esc.d}{basedir}`.
 
 ```xml
 <project>
@@ -46,7 +46,7 @@ First you must configure the plugin and tell it where your 
template is. In this
         <version>${project.version}</version>
         <configuration>
           <template>my-announcement.vm</template>
-          <templateDirectory>our-announcements</templateDirectory>
+          <templateDirectory>src/announcement</templateDirectory>
         </configuration>
       </plugin>
     </plugins>
@@ -58,7 +58,8 @@ First you must configure the plugin and tell it where your 
template is. In this
 Creating Your Template
 ----------------------
 
-Next you want to create your own template. A wise thing is to start with the 
default one that is included in the plugin. You can download it from 
[here](https://github.com/apache/maven-changes-plugin/blob/master/src/main/resources/org/apache/maven/plugins/announcement/announcement.vm).
 It will provide you with examples on how to iterate over the actions of a 
release among other things.
+Next you want to create your own template. A wise thing is to start with the 
default one that is included in the plugin. You can find it in the source 
repository:
+[announcement.vm](https://github.com/apache/maven-changes-plugin/blob/master/src/main/resources/org/apache/maven/plugins/changes/announcement/announcement.vm).
 It will provide you with examples on how to iterate over the actions of a 
release among other things.
 
 Available Variables
 -------------------
@@ -67,7 +68,7 @@ Here's a list of the variables that you have at your 
disposal, when creating you
 
 |Variable|Type|Since|Description|
 |:---|:---|:---|:---|
-|releases*|List|2.0|All the releases from either the changes.xml file or from 
JIRA.|
+|releases*|List|2.0|All the releases from the changes.xml file or the issue 
tracker.|
 |groupId*|String|2.0|The groupId from your project's pom.|
 |artifactId*|String|2.0|The artifactId from your project's pom.|
 |version*|String|2.0|The version from your project's pom.|
@@ -75,10 +76,10 @@ Here's a list of the variables that you have at your 
disposal, when creating you
 |release*|Release|2.0|The release that you are announcing.|
 |project*|MavenProject|2.1|The Maven Project being released.|
 |url|String|2.0|Distribution url of the artifact. **Default value is**: 
`${esc.d}{project.url}`.|
-|introduction|String|2.0|A short description or introduction of the released 
artifact. **Default value is**: `${esc.d}{project.description}`.|
+|introduction|String|2.0|A short description or introduction of the released 
artifact. **Default value is**: `${esc.d}{project.description}`, or `url` if 
that is empty.|
 |developmentTeam|String|2.0|Name of the team that develops the artifact. 
**Default value is**: `${esc.d}{project.name} team`.|
 |finalName|String|2.0|The name of the artifact to be used in the announcement. 
**Default value is**: `${esc.d}{project.build.finalName}`.|
-|urlDownload|String|2.0|URL where the artifact can be downloaded. **Default 
value is**: `${esc.d}{project.url}`.|
+|urlDownload|String|2.0|URL where the artifact can be downloaded. No default 
value.|
 |announceParameters|Map|2.1|A Map of custom parameters that can be specified 
in the plugin's configuration.|
 [Variables marked with \* are read-only.]
 
@@ -109,4 +110,4 @@ Finally each `Action` has the following variables:
 
 Velocity Context contains all default tools provided by the 
[ToolManager](https://velocity.apache.org/tools/devel/standalone.html). See the 
[Tools Usage 
Summary](https://velocity.apache.org/tools/devel/tools-summary.html) for 
further details.
 
-For information on how to access variables in your template and more, see the 
[Velocity user 
guide](https://velocity.apache.org/engine/devel/developer-guide.html).
+For information on how to access variables in your template and more, see the 
[Velocity user guide](https://velocity.apache.org/engine/devel/user-guide.html).
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index 11b5c9b..5551073 100644
--- a/src/site/markdown/faq.md
+++ b/src/site/markdown/faq.md
@@ -26,33 +26,28 @@ under the License.
 # Frequently Asked Questions
 
 1. [What's the difference between the changes-maven-plugin at Mojo and this 
one?](#question1)
-2. [I get a `org.xml.sax.SAXParseException`, when generating the JIRA Report. 
What can do about it?](#question2)
+2. [I get a `org.xml.sax.SAXParseException` when generating the JIRA Report. 
What can I do about it?](#question2)
+3. [Why does the Changes Report link to the wrong issue URL?](#question3)
 
 <a id="question1"></a>
 
 ### What's the difference between the changes-maven-plugin at Mojo and this 
one?
 
-This plugin started out at [the Mojo project](http://mojo.codehaus.org/). In 
March of 2006 the plugin was moved
-to Apache and the Maven sandbox. So it's the same plugin, but this one is 
newer.
+This plugin started out at the Mojo project (now 
[MojoHaus](https://www.mojohaus.org/)). In March of 2006 the plugin
+was moved to Apache. So it's the same plugin, and this one is the maintained 
version.
 
 <a id="question2"></a>
 
-### I get a `org.xml.sax.SAXParseException`, when generating the JIRA Report. 
What can do about it?
+### I get a `org.xml.sax.SAXParseException` when generating the JIRA Report. 
What can I do about it?
 
-If you have a lot of entities in the xml file returned from your JIRA 
installation, you might get an error like
-this one, when you run the JIRA Report:
+Old versions of the plugin downloaded issues as XML from JIRA and could hit 
the parser's entity expansion limit.
+The plugin now reads issues through the JIRA REST API, which returns JSON, so 
this error no longer occurs. Upgrade to
+the latest version of the plugin.
 
-```
-org.xml.sax.SAXParseException: Parser has reached the entity expansion limit 
"64,000" set by the Application.
-```
+<a id="question3"></a>
 
-If that happens you need to tell the xml parser to use a higher limit. This 
can be accomplished by adding a
-command line parameter. In the following example we have set it to double the 
original value:
+### Why does the Changes Report link to the wrong issue URL?
 
-```
-mvn -DentityExpansionLimit=128000 ...
-```
-
-Unfortunately we have not been able to set this in Java. If someone knows how 
to do this, then please reopen
-[MCHANGES-75](https://issues.apache.org/jira/browse/MCHANGES-75), and tell us 
how. It would be nicer if this
-could be set using a parameter in the POM.
+The link is built from `<issueManagement>/<url>` with the last `/` and 
everything after it removed. For GitHub, end
+the URL with a slash (`https://github.com/example/project/issues/`). See
+[Linking to Your Issue Management 
System](./usage.html#Linking_to_Your_Issue_Management_System).
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index 10e20d4..5d1567b 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -25,63 +25,113 @@ under the License.
 -->
 
 # Apache Maven Changes Plugin
-This plugin is used to inform your users of the changes that have occurred 
between different releases of your project. The plugin can extract these 
changes, either from a `changes.xml` file or from an issue management system 
(Jira, Trac and GitHub supported), and presents them as a report.
 
-You also have the option of creating a release announcement and even sending 
it via email to your users.
+The Changes Plugin tells your users what changed between releases of your 
project. It reads the changes either
+from a `changes.xml` file that you keep in the project, or from an issue 
tracker (JIRA, GitHub or Trac), and turns
+them into a site report or a plain-text release announcement.
+
+Most users come for one of these tasks:
+
+- Publish a changes report built from `src/changes/changes.xml`. Add the 
`changes` report to the `<reporting>`
+  section and run `mvn site`, or run the report on its own:
+
+  ```
+  mvn changes:changes
+  ```
+
+- Publish a report of the issues in your tracker, here GitHub (configured in 
`<issueManagement>`):
+
+  ```
+  mvn changes:github-changes
+  ```
+
+- Check `changes.xml` against the schema and make sure the release you build 
has a release date:
+
+  ```
+  mvn changes:changes-validate changes:changes-check
+  ```
+
+- Generate a release announcement text in `target/announcement/`, and 
optionally send it by email:
+
+  ```
+  mvn changes:announcement-generate
+  ```
+
+The plugin requires Maven 3.9.0 or later and Java 8 or later.
 
 ## Goals Overview
 
-- [changes:announcement-mail](./announcement-mail-mojo.html) send a release 
announcement via email.
-- [changes:announcement-generate](./announcement-generate-mojo.html) generate 
a release announcement.
-- [changes:changes-check](./changes-check-mojo.html) check that the 
`changes.xml` file contains a valid release date.
-- [changes:changes-validate](./changes-validate-mojo.html) validate the 
`changes.xml` file.
-- [changes:changes](./changes-mojo.html) create a report from `changes.xml` 
file.
-- [changes:jira-changes](./jira-changes-mojo.html) create a report from issues 
downloaded from [JIRA](https://www.atlassian.com/software/jira/).
-- [changes:trac-changes](./trac-changes-mojo.html) create a report from issues 
downloaded from [Trac](https://trac.edgewall.org/).
-- [changes:github-changes](./github-changes-mojo.html) create a report from 
issues downloaded from [GitHub](https://github.com/).
+- [changes:changes](./changes-mojo.html) creates a report from the 
`changes.xml` file.
+- [changes:github-changes](./github-changes-mojo.html) creates a report from 
issues downloaded from
+  [GitHub](https://github.com/).
+- [changes:jira-changes](./jira-changes-mojo.html) creates a report from 
issues downloaded from
+  [JIRA](https://www.atlassian.com/software/jira).
+- [changes:trac-changes](./trac-changes-mojo.html) creates a report from 
issues downloaded from
+  [Trac](https://trac.edgewall.org/). Deprecated, see 
[below](#Deprecate_Trac_integration).
+- [changes:changes-validate](./changes-validate-mojo.html) validates the 
`changes.xml` file against its XML schema.
+- [changes:changes-check](./changes-check-mojo.html) checks that the 
`changes.xml` file contains a valid release date
+  for the current version.
+- [changes:announcement-generate](./announcement-generate-mojo.html) generates 
a release announcement.
+- [changes:announcement-mail](./announcement-mail-mojo.html) generates the 
release announcement and sends it by email.
+- [changes:help](./help-mojo.html) displays help information on the plugin.
+
+The goals `changes-report`, `github-report`, `jira-report` and `trac-report` 
are deprecated aliases of the report
+goals above; see [Report goals and output 
names](#Report_goals_and_output_names).
+
 ## Usage
 
-General instructions on how to use the Changes Plugin can be found on the 
[usage page](./usage.html). Some more specific use cases are described in the 
examples given below.
+General instructions on how to use the Changes Plugin can be found on the 
[usage page](./usage.html). Some more
+specific use cases are described in the examples given below.
 
-In case you still have questions regarding the plugin's usage, please have a 
look at the [FAQ](./faq.html) and feel free to contact the [user mailing 
list](./mailing-lists.html). The posts to the mailing list are archived and 
could already contain the answer to your question as part of an older thread. 
Hence, it is also worth browsing/searching the [mail 
archive](./mailing-lists.html).
+If you still have questions about the plugin's usage, have a look at the 
[FAQ](./faq.html) and contact the
+[user mailing list](./mailing-lists.html). The posts to the mailing list are 
archived and could already contain the
+answer to your question as part of an older thread.
 
-If you feel like the plugin is missing a feature or has a defect, you can fill 
a feature request or bug report in our [issue 
tracker](./issue-management.html). When creating a new issue, please provide a 
comprehensive description of your concern. Especially for fixing bugs it is 
crucial that the developers can reproduce your problem. For this reason, entire 
debug logs, POMs or most preferably little demo projects attached to the issue 
are very much appreciated. Of course, patches are wel [...]
+If the plugin is missing a feature or has a defect, file a feature request or 
bug report in our
+[issue tracker](./issue-management.html). Especially for bugs, the developers 
need to be able to reproduce your
+problem, so a small demo project or a debug log (`mvn -X`) helps a lot. Pull 
requests are welcome, too: contributors
+can check out the project from our [source repository](./scm.html) and find 
more information in the
+[guide to helping with 
Maven](https://maven.apache.org/guides/development/guide-helping.html).
 
 ## Migration to 3.x
 
 ### changes.xml - schema changes
 
-- you should update schema in your changes.xml to `2.0.0` - [Using the XML 
Schema](./using-changes-xsd.html).
-- tag `action/dueto` - was removed, you can put your data into existing 
`due-to` and `due-to-email` attributes of `action` tag, which can be comma 
separated.
-- tag `action/fixedIssues` - was changed to an attribute `fixed-issues` of 
**action** tag, it also can be comma separated.
-### Report goals and output names
+- Update the schema in your `changes.xml` to `2.0.0`; see [Using the XML 
Schema](./using-changes-xsd.html).
+- The element `action/dueto` was removed. Put its data into the `due-to` and 
`due-to-email` attributes of the
+  `action` element, which accept comma-separated lists.
+- The element `action/fixedIssues` was changed to the attribute `fixed-issues` 
of the `action` element, which also
+  accepts a comma-separated list.
 
-The reports output filename and goals name were changed for alignment with 
other reporting plugins from `org.apache.maven.plugins`.
+### Report goals and output names
 
-See the following table for changes:
+The report goals and their output file names were renamed in line with the 
other reporting plugins from
+`org.apache.maven.plugins`. The old goal names still work but are deprecated.
 
-|goal name|output name|
-|:---|:---|
-|changes-report -&gt; changes|changes-report.html -&gt; changes.html|
-|github-report -&gt; github-changes|github-report.html -&gt; 
github-changes.html|
-|jira-report -&gt; jira-changes|jira-report.html -&gt; jira-changes.html|
-|trac-report -&gt; trac-changes|trac-report.html -&gt; trac-changes.html|
+|Old goal name|New goal name|Old output name|New output name|
+|:---|:---|:---|:---|
+|changes-report|changes|changes-report.html|changes.html|
+|github-report|github-changes|github-report.html|github-changes.html|
+|jira-report|jira-changes|jira-report.html|jira-changes.html|
+|trac-report|trac-changes|trac-report.html|trac-changes.html|
 
 ### Deprecate Trac integration
 
-**Trac** integration is prepared for removal in next major version due to lack 
of maintainers.
+The **Trac** integration is prepared for removal in the next major version due 
to lack of maintainers. The
+`trac-changes` goal is deprecated already.
 
 ## Examples
 
-To provide you with better understanding of some usages of the Changes Plugin, 
you can take a look at the following examples:
+To provide you with better understanding of some usages of the Changes Plugin, 
you can take a look at the following
+examples:
 
 - [Alternate Location for the `changes.xml` 
File](./examples/alternate-changes-xml-location.html)
 - [Check Your `changes.xml` File](./examples/check-changes-file.html)
-- [Configuring the Trac Report](./examples/configuring-trac-report.html)
-- [Customizing the JIRA Report](./examples/customizing-jira-report.html)
+- [Validate Your `changes.xml` File](./examples/changes-file-validation.html)
 - [Configuring the GitHub Report](./examples/configuring-github-report.html)
+- [Customizing the JIRA Report](./examples/customizing-jira-report.html)
+- [Configuring the Trac Report](./examples/configuring-trac-report.html)
 - [Include an Announcement File in Your 
Packaging](./examples/include-announcement-file.html)
-- [SMTP authentication](./examples/smtp-authentication.html)
-- [Specifying the mail sender](./examples/specifying-mail-sender.html)
 - [Using a Custom Announcement 
Template](./examples/using-a-custom-announcement-template.html)
-- [Validate Your `changes.xml` File](./examples/changes-file-validation.html)
+- [Specifying the Mail Sender](./examples/specifying-mail-sender.html)
+- [SMTP Authentication](./examples/smtp-authentication.html)
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index b57b114..d53fabd 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -28,12 +28,14 @@ under the License.
 
 # 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.
+This plugin creates a Changes Report from a `changes.xml` file, issue reports 
from JIRA, GitHub or Trac, and a
+release announcement text. It can also send the announcement by 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:
+Create a `changes.xml` file in the `src/changes/` directory. Here's an example 
of a typical `changes.xml`, showing
+the syntax:
 
 ```xml
 <document xmlns="http://maven.apache.org/changes/2.0.0";
@@ -41,24 +43,26 @@ In order to use this goal, simply create a `changes.xml` 
file in the `src/change
           xsi:schemaLocation="http://maven.apache.org/changes/2.0.0 
https://maven.apache.org/xsd/changes-2.0.0.xsd";>
   <properties>
     <title>Changes Tester Project</title>
-    <author email="[email protected]">Johnny R. Ruiz III</author>
+    <author email="[email protected]">John Smith</author>
   </properties>
   <body>
-    <release version="1.1" date="2005-03-01" description="Subsequent release">
-      <action dev="jruiz" type="add">
+    <release version="1.1" date="2026-03-01" description="Subsequent release">
+      <action dev="jsmith" type="add">
         Added additional documentation on how to configure the plugin.
       </action>
-      <action dev="aramirez" type="fix" issue="MPJIRA-11">
+      <action dev="jdoe" type="fix" issue="PROJ-11">
         Enable retrieving component-specific issues.
       </action>
-      <action dev="jruiz" type="remove" due-to="Allan Ramirez" 
due-to-email="[email protected]">
-        The element type " link " must be terminated by the matching end-tag.
+      <action dev="jsmith" type="remove" due-to="Jane Roe, Joe Bloggs" 
due-to-email="[email protected], [email protected]">
         Deleted the erroneous code.
       </action>
+      <action dev="jsmith" type="update" fixed-issues="PROJ-12,PROJ-13">
+        Updated the default announcement template.
+      </action>
     </release>
 
-    <release version="1.0" date="2005-01-01" description="First release">
-      <action dev="jruiz" type="update">
+    <release version="1.0" date="2026-01-01" description="First release">
+      <action dev="jsmith" type="update">
         Uploaded documentation on how to use the plugin.
       </action>
     </release>
@@ -66,7 +70,8 @@ In order to use this goal, simply create a `changes.xml` file 
in the `src/change
 </document>
 ```
 
-See the [Changes Reference](./changes.html) for details regarding the 
`<release>` and `<action>` elements and their attributes.
+See the [Changes Reference](./changes.html) for details regarding the 
`<release>` and `<action>` elements and their
+attributes. The supported action types are `add`, `fix`, `update` and `remove`.
 
 To generate the Changes Report, insert the Changes Plugin in the `<reporting>` 
section of your project's `pom.xml`
 
@@ -99,26 +104,34 @@ and execute the `site` phase to generate the report.
 mvn site
 ```
 
+You can also run the report on its own; it is written to 
`target/reports/changes.html`:
+
+```
+mvn changes:changes
+```
+
 #[[### 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.
+If you use the `issue` or `fixed-issues` attribute in your `changes.xml` file 
and have the `<issueManagement>`
+element configured in your `pom.xml`, the report links each issue to 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:
+The plugin comes pre-configured for many issue management systems. All you 
have to do is enter your issue management
+system and its URL in your POM. It can look like this:
 
 ```xml
 <project>
   ...
   <issueManagement>
     <system>JIRA</system>
-    <url>http://jira.company.com/</url>
+    <url>https://jira.example.com/browse/PROJ</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.
+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. The value of
+`<issueManagement>/<system>` must match the name in the first column, ignoring 
case.
 
 |System|Issue Link Template|
 |:---|:---|
@@ -128,24 +141,31 @@ The following table shows the pre-configured issue 
management systems and the te
 |GoogleCode|%URL%/detail?id=%ISSUE%|
 |JIRA|%URL%/%ISSUE%|
 |Mantis|%URL%/view.php?id=%ISSUE%|
-|MKS Integrity|%URL%/viewissue?selection=%ISSUE%|
+|MKS|%URL%/viewissue?selection=%ISSUE%|
 |Redmine|%URL%/issues/show/%ISSUE%|
 |Scarab|%URL%/issues/id/%ISSUE%|
-|SourceForge|http\://sourceforge.net/support/tracker.php?aid=%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 
[configure an issue link template for 
it](./changes-mojo.html#issueLinkTemplatePerSystem). 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 [creating an 
issue for it](./issue-tracking.html).
+If you use an issue management system other than the ones above, or need to 
link to more than one, you need to
+[configure an issue link template for 
it](./changes-mojo.html${esc.hash}issueLinkTemplatePerSystem). 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 [creating an issue for 
it](./issue-management.html).
 
-**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`.
+**Note:** `%URL%` is the value of `<issueManagement>/<url>` with the last `/` 
and everything after it removed. For
+JIRA, `https://jira.example.com/browse/PROJ` gives links like 
`https://jira.example.com/browse/PROJ-11`. For GitHub,
+end the URL with a slash, as in `https://github.com/example/project/issues/`, 
so that the links point to
+`https://github.com/example/project/issues/11`; without the trailing slash the 
`issues` part is dropped.
 
 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:
+**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:
 
 ```xml
 <project>
@@ -158,7 +178,8 @@ How to Generate the JIRA Report
 </project>
 ```
 
-To generate the JIRA Report, insert the Changes Plugin in the `<reporting>` 
section of your project's `pom.xml`
+The plugin reads the issues through the JIRA REST API. To generate the JIRA 
Report, insert the Changes Plugin in the
+`<reporting>` section of your project's `pom.xml`
 
 ```xml
 <project>
@@ -189,19 +210,21 @@ and execute the site goal to generate the report.
 mvn site
 ```
 
-For info on how to modify the JIRA Report see the [Customizing the JIRA 
Report](./examples/customizing-jira-report.html) example.
+For info on how to modify the JIRA Report see the [Customizing the JIRA 
Report](./examples/customizing-jira-report.html)
+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:
+**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:
 
 ```xml
 <project>
   ...
   <issueManagement>
     <system>GitHub</system>
-    <url>https://github.com/rails/rails/issues</url>
+    <url>https://github.com/apache/maven-changes-plugin/issues/</url>
   </issueManagement>
   ...
 </project>
@@ -238,57 +261,25 @@ and execute the site goal to generate the report.
 mvn site
 ```
 
-For info on how to modify the JIRA Report see the [Configuring the GitHub 
Report](./examples/configuring-github-report.html) example.
+For info on how to modify the GitHub Report see the [Configuring the GitHub 
Report](./examples/configuring-github-report.html)
+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 [Specifying the mail 
sender](./examples/specifying-mail-sender.html) 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'.
-
-```xml
-<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">[email protected]</toAddress>
-            <toAddress 
implementation="java.lang.String">[email protected]</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:
+The `announcement-generate` goal writes the announcement text, by default to
+`target/announcement/announcement.vm`. Set `<announcementFile>` to choose 
another file name. By default the
+announcement is built from the `changes.xml` file:
 
 ```
 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:
+To build the announcement from an issue tracker instead, list it in 
`<issueManagementSystems>`. Valid values are
+`changes.xml`, `JIRA`, `GitHub` and `Trac`; the tracker must also be the one 
configured in `<issueManagement>`.
+To generate the announcement based on **both** a `changes.xml` file and JIRA 
you should configure your `pom.xml`
+like this. `<onlyCurrentVersion>` makes JIRA return the issues of the version 
you release; without it, the plugin
+fetches only the latest `<maxEntries>` (25) issues, which might not include 
that version:
 
 ```xml
 <project>
@@ -300,11 +291,11 @@ If you want to generate the announcement based on JIRA 
you need to configure tha
         <artifactId>maven-changes-plugin</artifactId>
         <version>${project.version}</version>
         <configuration>
-          ...
           <issueManagementSystems>
+            <issueManagementSystem>changes.xml</issueManagementSystem>
             <issueManagementSystem>JIRA</issueManagementSystem>
           </issueManagementSystems>
-          ...
+          <onlyCurrentVersion>true</onlyCurrentVersion>
         </configuration>
       </plugin>
     </plugins>
@@ -313,7 +304,21 @@ If you want to generate the announcement based on JIRA you 
need to configure tha
 </project>
 ```
 
-To generate the announcement based on **both** a `changes.xml` file and JIRA 
you should configure your `pom.xml` like this:
+The announcement groups issues from a tracker by action type: _add_, _fix_, 
_update_ or _remove_. By default, for
+JIRA, _add_ corresponds to 'New Feature', _fix_ to 'Bug', and _update_ to 
'Improvement', 'Task', 'Wish' and
+'Dependency upgrade'; for GitHub, _add_ corresponds to the label 'enhancement' 
and _fix_ to 'bug'. If your tracker uses
+other issue types, map them with `<issueTypes>`, separating several types with 
commas:
+
+```xml
+<configuration>
+  <issueTypes>
+    <add>Story</add>
+    <fix>Defect,Malfunction</fix>
+  </issueTypes>
+</configuration>
+```
+
+To send the announcement by email, configure the mail server and the 
recipients:
 
 ```xml
 <project>
@@ -325,12 +330,12 @@ To generate the announcement based on **both** a 
`changes.xml` file and JIRA you
         <artifactId>maven-changes-plugin</artifactId>
         <version>${project.version}</version>
         <configuration>
-          ...
-          <issueManagementSystems>
-            <issueManagementSystem>changes.xml</issueManagementSystem>
-            <issueManagementSystem>JIRA</issueManagementSystem>
-          </issueManagementSystems>
-          ...
+          <smtpHost>mail.example.com</smtpHost>
+          <smtpPort>25</smtpPort>
+          <toAddresses>
+            <toAddress>[email protected]</toAddress>
+            <toAddress>[email protected]</toAddress>
+          </toAddresses>
         </configuration>
       </plugin>
     </plugins>
@@ -339,8 +344,11 @@ To generate the announcement based on **both** a 
`changes.xml` file and JIRA you
 </project>
 ```
 
-This is how you send an email with the generated announcement:
+The `announcement-mail` goal runs `announcement-generate` first and then sends 
the result:
 
 ```
 mvn changes:announcement-mail
 ```
+
+For info on how to change the sender of the email see the [Specifying the Mail 
Sender](./examples/specifying-mail-sender.html)
+example, and for a server that needs a login see [SMTP 
Authentication](./examples/smtp-authentication.html).
diff --git a/src/site/markdown/using-changes-xsd.md 
b/src/site/markdown/using-changes-xsd.md
index 272fc5b..682b068 100644
--- a/src/site/markdown/using-changes-xsd.md
+++ b/src/site/markdown/using-changes-xsd.md
@@ -26,7 +26,9 @@ under the License.
 
 # Using the XML Schema Changes 2.0.0
 
-The Changes XSD is located 
[here](https://maven.apache.org/xsd/changes-2.0.0.xsd).
+The current version of the `changes.xml` schema is 2.0.0. The XSD is published 
at
+<https://maven.apache.org/xsd/changes-2.0.0.xsd>, and a copy is part of this 
site:
+[changes-2.0.0.xsd](./xsd/changes-2.0.0.xsd).
 
 Your favorite IDE probably supports validation and/or syntax highlighting for 
XML files by using XSD schemas. For this to work you need to specify the schema 
in your `changes.xml` file:
 
@@ -37,3 +39,6 @@ Your favorite IDE probably supports validation and/or syntax 
highlighting for XM
 ...
 </document>
 ```
+
+To validate the file during the build, use the 
[changes-validate](./changes-validate-mojo.html) goal; see
+[Validate Your changes.xml File](./examples/changes-file-validation.html).
diff --git a/src/site/site.xml b/src/site/site.xml
index 3695cb6..4f7f518 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -37,20 +37,17 @@ under the License.
       <item name="changes.xml" href="changes.html"/>
       <item name="changes.xsd" href="xsd/changes-2.0.0.xsd"/>
     </menu>
-    <menu name="Samples">
-      <item name="Sample Changes Report" href="changes.html"/>
-    </menu>
     <menu name="Examples">
       <item name="Alternate Location for the changes.xml File" 
href="examples/alternate-changes-xml-location.html"/>
       <item name="Check Your changes.xml File" 
href="examples/check-changes-file.html"/>
-      <item name="Configuring the Trac Report" 
href="examples/configuring-trac-report.html"/>
-      <item name="Customizing the JIRA Report" 
href="examples/customizing-jira-report.html"/>
+      <item name="Validate Your changes.xml File" 
href="examples/changes-file-validation.html"/>
       <item name="Configuring the GitHub Report" 
href="examples/configuring-github-report.html"/>
+      <item name="Customizing the JIRA Report" 
href="examples/customizing-jira-report.html"/>
+      <item name="Configuring the Trac Report" 
href="examples/configuring-trac-report.html"/>
       <item name="Include an Announcement File in Your Packaging" 
href="examples/include-announcement-file.html"/>
-      <item name="SMTP Authentication" 
href="examples/smtp-authentication.html"/>
-      <item name="Specifying the Mail Sender" 
href="examples/specifying-mail-sender.html"/>
       <item name="Using a Custom Announcement Template" 
href="examples/using-a-custom-announcement-template.html"/>
-      <item name="Validate Your changes.xml File" 
href="examples/changes-file-validation.html"/>
+      <item name="Specifying the Mail Sender" 
href="examples/specifying-mail-sender.html"/>
+      <item name="SMTP Authentication" 
href="examples/smtp-authentication.html"/>
     </menu>
   </body>
 </site>

Reply via email to